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1.9 INTRODUCTION AND GUIDELINES TO THIS MANUAL 


This manual is a guide and a reference source for the person using 
VSAM. 


This document has not been submitted to any formal IBM test and has 
not been checked for technical accuracy. Potential users should 
evaluate its usefullness in their own environment prior to any 
implementation. 


We want to acknowledge our debts to the many individuals who gave 
us assistance in answering technical questions. In particular we 
want to give credit to Roman Chiocca from Switzerland and David 
Pepper from Nottingham, England for. their participation in develop- 
ment of this document. 


1.1 DESCRIPTION OF THIS MANUAL 


The objectives of this manual are: 


e To give the new VSAM user the information required to under- 
stand, evaluate, and use VSAM properly. 


e To clarify VSAM £unctions for current VSAM application program- 
mers who will be working with VSAM. The practical, straightfor- 
ward approach adopted should dispel much of the apparent 
complexity sometimes associated with VSAM. 


Wherever possible an example is used to reinforce a description, 
and a modified version of the same example is used in any related 
section to give continuity to the explanation. Diagrams are used 
liberally to aid understanding. 


This manual is not operating system dependent and is intended for 
DOS/VS, MVS, SVS, and VS1 users, who should have some familiarity 
With access methods. 


Information contained in this manual includes: 
e A general description of VSAM and Access Method Services 


concepts and capabilities, including catalog usage and compari- 
sons With other access methods. 


e Methods of calculating storage and data set space requirements. 

° General system considerations. 

e Descriptions and examples of using Access Method Services 
facilities. 

e An explanation of VSAM installation procedures. 

° Programming considerations. 

° Performance considerations. 


Chapter 1. Guidelines 1 


° Integrity considerations. 


This manual is not intended as a replacement for the SRL manuals 
and IBM courses, but as a supplement to them. It will be particu- 
larly useful as an initial point of reference to give a basic 
understanding in specific areas, which may then be followed up by 
reference to the appropriate SRL manual or course. For example, 
though this manual gives an understanding of the principles of 
programming with VSAM, reference manuals would be needed to actual- 
ly write code. Likewise, a clear understanding of how to use Access 
Method Services commands to create, modify, delete, print and move 
data sets is given, but the appropriate manual or course is neces- 
sary to properly code actual commands. | 


This manual is a learning guide and a source of £field-developed 
techniques and advice. It does not eliminate the need for careful 
planning and education. This publication therefore intends to 
show, in an uncomplicated way, how to use VSAM simply and effec- 
tively. 


Knowledge of concepts of Virtual Storage Systems (like DOS/VS, 


MVS,SVS,VS1) is required. Basic knowledge of other Access Methods 
(like SAM or ISAM) is desirable. 


1.2 HOW TO USE THIS MANUAL 


1.2.1 DOS/VS AND OS/VS USERS 


All chapters can be followed in the order they are presented. 
Specific information is included in the Appendices. The index at 
the end of the manual can be used to find a specific item. 


Restrictions or notes to specific Operating Systems are added where 
applicable. 


1.2.2 MVS USERS NOT USING VSAM APPLICATIONS 


Each MVS System must have a VSAM master catalog as the main system 
catalog. 


Even if a user does not plan to use VSAM applications, he should be 
familiar with the basic VSAM structures (as the VSAM master catalog 
1s also a VSAM data set). 


The most important chapters for this group of user are the chapters 
2.9, 3.0, 6.0, and appendix &A.0O. 


It is suggested, however, to also read the other chapters, as most 
of them also contain information important for users, using only 
VSAM catalogs. 
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2.9 WHAT IS VSAM 


2-1 BASIC DESCRIPTION OF VSAM 


Virtual Storage Access Method (VSAM) is a component of DBOS/VS and 
OS/VS data management and is supported in DOS/VS, OS/VS1, OS/VS2 
SVS, and OS/VS2 MVS. In VM/370 the CMS/VSAM support is based on 
DOS/VS. 


The VSAM Assembler Language macros used in DOS/VS and OS/VS are 
compatible. In addition, a VSAM data set contained on a DOS/VS 


volume can be processed by OS/VS- programs. Similarly, a VSAM data 
set contained onan OS/VS volume can be processed by DOS/VS 
programs. This compatibility enables VSAM data sets to be 


processed both by DOS/VS and OS/VS, and makes a transition £from 
DOS/VS to OS/VS much easier. | 


VSAM supports both sequential and direct processing and is designed 
to supersede ISAM, although the two access methods can coexist in 


the same Operating System. VSAM supports functions equivalent to 
those of ISAM, and provides better performance (see description 
starting in section 5.4 on page 75). VSAM data sets cannot be 


accessed by any other Access Method. 


In addition, the three data organizations supported by VSAM can be 
used in place of BSAM or @SAM for sequential data sets and in place 
of BDAM for directly organized data sets (see description starting 
in section 5.1 on page 71). The new structure and features of VSAM 
make it more suited to data base and online environments than other 
access methods. 


VSAM support consists of the following: 


e Three data set organizations : Entry-Sequenced Data Sets 
CESDS), Key-Sequenced Data Sets (KSDS), and Relative-Record 
Data Sets CRRDS). The user can thus choose the logical data 
organization that is best suited for his or her particular 
needs. They are supported on DASD (Direct Access Storage 
Device) only. 


= A VSAM ESDS is a sequential data set (Similar to a SAM data 
set). 


- A VSAM KSDS is a sequential data set with an index (similar 
to an ISAM data set). 


= A VSAM RRDS is a data set with preformatted slots for fixed 


length records to he accessed by a record number (similar 
to a DAM data set). . 


° VSAM master and user catalogs which contain information about 
VSAM data sets, volumes, spaces, etc. 
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° The multifunction utility program Access Method Services, which 
provides required VSAM services, such as catalog or data set 
creation, loading, mérging, printing, and VSAM catalog mainte- 
nance. This utility supports DASD as well as tape devices. 


e Access method routines with which the user interfaces to 
process logical records in VSAM data sets. 


e The ISAM interface routines, which make the transition from 


ISAM to VSAM possible with little or no modification of ISAM 
programs. | | | 


2.1.1 CREATING VSAM OBJECTS 


Unlike nonVSAM data sets which are usually created by using JCL, 
VSAM objects (VSAM objects are data sets, data spaces, catalogs, 
etc.) Nay only be created by using the utility Access Method 
Services. | - | : 


One group of commands creates VSAM objects. These are the DEFINE 
commands. | | - ¥ 


The term 'defining' a VSAM object means creating an entry in a VSAM 
catalog without any data transfer. The contents of the object may 
be loaded with a user program or with Access Method Services. 


For further information and an overview of the various Access 
Method Services commands, see chapter 4.0 starting on page 57. 


2.2 VSAM DATA SET STRUCTURE 


The logical records of VSAM data sets are stored differently from 
the way in which logical records in nonVSAM data sets are stored. 


2.2.1 CONTROL INTERVALS 


It is fairly obvious that transferring a single data record ora 
complete data set between virtual and auxiliary storage could be an 
inefficient and time-consuming way of processing records. What is 
needed is to structure data records in a way to make VSAM as 
efficient as possible. | 


To accomplish this, so-called control intervals have been designed 
to contain the data records. The disk space on a direct access 
storage device (like IBM 3330, 3340, 3344, and 3350) has been 
divided into segments of information. The size of the segments can 
vary from one VSAM data set to another VSAM data set, but fora 
specific data set, the size of each segment is fixed, either by 
VSAM or by the the user (within limits acceptable to VSAM). These 
segments of information are called control intervals. Figure 1 
illustrates the data records (Cand the control information descri- 
bing them) stored in a control interval. | 
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A-control interval is the unit of data transferred between virtual 
storage and disk storage; for example VSAM will transfer the 
control interval shown in figure 1 to virtual storage if one or 
more o£ the data records in that control interval needs to be 
updated, deleted, etc. 


c£ = control fields 
us = unused space 


Figure 1.Control Interval 


The control interval suet be a certain size C( a multiple of 512 
bytes unless the control interval-size is greater than 8192, then 
the multiple is 2048). The maximum size of a control interval is 
32,768 bytes. 


If the user specified control interval is different from the 
allowed sizes (see page 195), VSAM will substitute the define 
value by a default value (the control interval size should he 
carefully chosen, since a large default control interval will 
demand corresponding large buffer space). 


A control interval can Span several tracks depending on control 
interval size and track capacity but it cannot cross control area 
boundaries (the control area is described in the next section). 


A control interval always contains control information fields plus 
an integral number of logical records (variable or fixed-length), 
and unused (free) space, or data records alone, or free space 
alone. A record may cross more than one control interval only when 
the data set has been defined with spanned format (described in 
section 2.2.3 on page 11). | 


Figure 2 shows that control information fields consist of two types 


of fields: one CIDF (Control Interval Definition Field), and one or 
more RDFs (Record Definition aera 


| ort] vn] | pan | unused space space RDFn| npr? | RDF! DFT cxpF| 


= data record 

Figure 2.Control interval structure with control fields 

There is one Control I terval Definition Field (CIDF) per control 
interval and usually multiple Record Definition Fields (RDF) 
depending on the number of different logical records lengths. 

As there is no parameter in VSAM to define the data set records as 
fixed-length or variable-length records (like RECFM for DOS/VS or 
OS/VS data sets), VSAM takes into consideration the length of 
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adjacent records in a control interval when writing a record (see 
also description of parameter RECORDSIZE on page 94). If two or 
more adjacent records have the same length, only two RDFs are used 
for this group. See following examples for records of the same and 
different length. | : an ae 


RDFs describe length of record and how many adjacent records are of 
the same length. With fixed-length records, only two RDFS are 
used, even if more than 2 records are stored in the control inter- 
val. 


Control interval size 
Records of the same length 


512 bytes 
80 bytes Conly 2 RDFs (R a) in 
figure below needed). 


a 


Control interval size = 512 bytes 
For records of different length 1 RDF per LR is used 
CR 1 £f0r LR 1, R 2 £0r LR 2, etc.) 


er ec On ee noc 
«430 70 50 140 60 4 3 3. «3 3 3 3 \ 


Control interval size = 512 bytes 

Records of different length (for each group of adjacent records 
with the same length, 2 RDFs are used 

(R a for LR 1-4, R*5 for LR 5, and R® £for LR 6) 


Cn oon a] ee of ae afin foe ee [ee ome 
8 0 80 8 0 8 0 58 55 6 3 3 3 3 3 4 


Legend: 

LR = Logical Record 

£.s. = free space 2 

R x = Record Definition Field (3 bytes) 

CIDF = Control Interval Definition Field (4 bytes) 


The small numbers represent the length in bytes of 
data/control fields 


Figure 3. Control intervals with fixed and variable-length records 
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Each control interval is divided into one or more fixed-length 
physical records and VSAM determines their size based on the 
control interval size and the device characteristics. This physi- 
cal record is dependent on the control interval size and the device 
type and is purely a consideration when mapping control intervals 
to the storage device. A physical record is that record seen on 
the disk and its size is equal to the control interval wherever 
possible. 


By defining the CI-size for a data set stored on a specific type of 
direct access device, the user implicitly chooses the physical 
record size (for further details see page 196). 


The following ‘figure shows the relationship between user defined 
control interval size and VSAM chosen physical record size on 
different DASD types. In this example it is assumed the control 
interval size is 6K. As a control interval must be stored in an 
integral number of physical records the next lower value is 2K. So 
VSAM chooses 2K as physical record size for the 3330. Since 2K 1s 
not used on 3340 (would result in only 75% track utilization) 1K is 
choosen for 3340. Page 196 contains a chart showing the physical 
record sizes and the number of records per track for each supported 
DASD type. 


3340 


RIETEEEDC Ce ecegeness 


Le [ede p es [elo [Do [ov] pre 


Track 1 Track 2 


3330 


se 
ca ee [ae [ele] oe sf ee of oe of 
cafe [»[es][ =] * 


Track 1 


C = Control Fields (RDFs, CIDF) #CI = Control Interval 
fs = free space | LR = Logical Record 
P = Physical Record 


Figure 4. Logical to physical records relationship 
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With a single GET, one or more control intervals may be transferred 
between a VSAM data set and VSAM buffers in main storage (depending 
on direct or sequential access). Command-chained reads/writes are 
used when a control interval contains more than one physical disk 
record. From the VSAM buffer, the desired logical record (without 
control fields) is transferred to the user buffer (input area). 
For more information about specifying VSAM buffers, see section 
8.1.5 on page 190. | 


A logical record ina kKey~sequenced data set or in an entry-se- 
quenced data set (the data set organizations are described later) 
can span two or more control intervals within the same control 
area, in which case it is called a spanned record (see detailed 
description in section 2.2.3 on page 11). | | 


The physical Roeation of a logical record within a data set is 


given in the form of a relative byte address (RBA) rather than a 
CCHHR disk record address. 


The RBA of a logical record is the offset of this logical record 
from the beginning of the data set. The first record ina data set 
has an RBA of QO. The second record has an RBA equal to the length 
of the first record and’ so on. The RBA of a logical record or 
index entry, therefore, is independent of the physical characteris-— 
tics of the direct access device type on which it resides, the 
number of extents in the data set, etc. It only depends on its 
position in the sequence of records. This way of referencing data 
by RBA makes the data sets independent of the DASD device type. 


The RBA is always expressed as a £ull word binary integer. 


The RBA includes free space and control information bEEGUEC 8 on 
page 14 shows an example how RBA values are assigned). | 


2.2.2 CONTROL AREAS 


The control intervals ina VSAM data set are grouped together into 
fixed-length contiguous areas of direct-access storage called 
Control Areas (CAs). A control area is auxiliary storage space 
that is set aside by VSAM to receive or hold the control intervals 
of a particular data set. " & Y 


The user does not have to specify the number of control intervals 
per control area of a data set; VSAM determines this number. 
Whenever the space in a data set needs to be extended because the 
control area cannot hold anymore data, VSAM extends the data set 
(see also description of VSAM data spaces and space allocation on 
page 40, 45, 189). | | | 


The maximum size of a control area is one cylinder and the minimum 
size is one track of a DASD. The user implicitly defines ths 
control area size by specifying the amount of space to be allocated 
to a data set (for further information, see section 8.1.3.2 on page 
187). Usually better performance is obtained when the size of one 
control area is one cylinder. 


10 VSAM PRIMER and REFERENCE 


Figure 5 shows a possible structure of three control areas, used in 
the data component of a Key-sequenced data set (KSDS) (the data set 
organizations are explained in the next section), which include 
four control intervals each. 


All details, like ‘free space', etc., are explained in following 
sections. 


cL 1 
CI 2 
CA 1 
CI 3 
CrI 4 
CI 5 
CI 6 
CA 2 
Ci 7 
CI 8 
CI 9 
CI 10 
CA 3 , | 
CI 12 free control interval ic. 


C = Control Interval Definition Field 
CA = Control Area 
CI = Control Interval 
fs = £ree space 

R = Record Definition Field 


Figure 5. Structure of a VSAM control area (KSDS) 


2.2.3 SPANNED RECORDS 


If the data records are larger than the control interval size they 
need not be broken apart or be reformated; it can be specified 
(with the SPANNED parameter in the Access Method Services DEFINE 
command, Which is described later) that they are allowed to extend 
across or span control interval boundaries. 
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Such records are called spanned records. Spanned records are 
applicable only to KSDS and RRDS data sets. | | 


A spanned record must always begin on a control interval boundary; 
it fills one or more control intervals within a single control 
area. As shown in figure 6, the control interval that contains the 
last portion (segment) of a spanned record contains unused space if 
the segment does not completely fill the data space available in 
the control interval. This unused space can only be used to extend 
the spanned record; it cannot contain all or part of any other 
record. | 


If the parameter SPANNED was specified at DEFINE time (this parame- 
ter cannot be changed with ALTER; described later), VSAM determines 
dependent on the length of each record whether it is a spanned or a 
nonspanned record. If the record length is larger than CI size 
minus 7 (CRDF+CIDF) the record is stored as spanned record starting 
in a new CI (this is also checked when a record is extended). 


If spanned records are used for KSDS, the primary Key must be 
Within the first control interval. 


‘ 


\ 


CI 2 | 


data red part 1 data red p.2 


C = Control fields (10 bytes = 2 RDF + 1 CIDF) 
* = Unused space 


Figure 6. Structure of a spanned record 


2.3 TYPES OF DATA SETS 


VSAM supports three different data set organizations: 
key-sequenced, entry-sequenced, and relative-record. All three 
organizations allow both sequential and direct processing and 
record addition without rewrite of the complete data set. The 
primary difference between these three organizations is the 


sequence in which logical records are stored. 


A key-sequenced data set (KSDS) uses logical records, either fixed 
or variable in length, which are placed in the data set in ascend- 
ing collating sequence by a field, called the Key. 


To differentiate Keys used in VSAM objects the key used ina base 
cluster (explained on page 29) is called a primary Key or base key. 
The key used in an alternate index (explained on page 29) is called 
an alternate Key. 3 | 


12 VSAM PRIMER and REFERENCE 


Records added after the KSDS is created are inserted in primary Key 
sequence and existing logical records are moved when necessary. In 
VSAM kKey-sequenced organization, a record must have a unique, 
embedded, fixed-length primary Key located in the same position 
Within each logical record. Primary keys can be a minimum of one 
byte and a maximum of 255 bytes. 


To differentiate indexes used in VSAM objects the index in a KSDS 
base cluster is called the primary index (usually, the term ‘index' 
in this manual means ‘primary index'). A primary index is always 
created for a KSDS. 


An optional index which can be built over an ESDS or KSDS base 
cluster is called an alternate index (the alternate index is 
described on page 29). The alternate index enables logical records 
to be accessed sequentially or directly through a different field. 
An alternate index is organized like a KSDS. 


Figure 7 shows a logical picture of a KSDS with one control area 
which includes four control intervals (physically the entries in an 
index control interval are stored from right to left): 


index 


set 


wer | 
ror erarelols eae 
as 
cd ee 
a 


pointer to free control interval 
a = control fields (RDFs, CIDF) 


logical 


records 


Pa 


us = unused space 
R = RDF CRecord Definition Field) 
C = CIDF (Control Interval Definition Field) 


Figure 7. Key-sequenced data set structure 
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The KSDS and its components are described in more detail starting 
on page 18. | 


An entry-sequenced data set (ESDS), which is logically comparable 


to a SAM data set, contains either fixed- or variable-length 
records, sequenced in the order in which they were submitted for 
inclusion in the data set (like SAM data sets). Therefore, records 


are sequenced by their time of arrival rather than by any field in 
the logical record. 


An ESDS accepts records of fixed and variable length, spanned or 
nonspanned records (spanned records are described on page 11). 
Records can be added at the end, and records can be updated but not 
extended. Records cannot be erased. 


Figure 8 shows a possible structure of an ESDS. The RBA values 
are in hexadecimal (RBA values are always presented in a 4-b; ve 
field). 


The numbers in the CIs represent keys in the records (not used when 
loading the data set or as search arguments). The control interval 
length is 512 bytes. The small numbers below the CIs represent the 
record/field length in bytes. 


RBA 
ia " q "| ae i 1BB i _ 


i 


? 3 3. 3 3S. 3 


RBA | | 
ie a 7 a i ey — oa o% eg 


ese aw a 


7&8 #3 $3 3 3 3 


RBA = 
i a U5D ii GCF 50D Big 7. an 


3 3 3 3 3 & 


CIDF (Control Interval Definition Field) 


C = 
nus = unusable space (remaining space) 
R = RDF (Record Definition Field) 
RBA = Relative Byte Address (see page 10) 


Figure 8. Entry-sequenced data set structure 
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A relative record data set (RRDS) is processed by a relative record 
number and consists of a number of non-spanned fixed-length slots, 
each of which has a unique relative record number, an associated 
RDF, and contains one logical record. The slots within an RRDS are 
sequenced by ascending relative record number (from 1 to N). 


A record is placed in the slot specified by a user-supplied rela- 
tive record number (for direct or skip-sequential inserts) or, if 
not specified, by a VSAM-supplied relative record number (for 
initial load or sequential inserts). This relative record number 
is never included in the logical record by VSAM. 


Records can be retrieved by relative record number (direct, 
skip-sequential) or by physical sequence). Insertion and proces- 


Sing techniques are explained in section 2.6 on page 22. 


In an RRDS one RDF (3 bytes) per slot is used, and Bit 5 in the 


first byte of each RDF determines, if a slot is ‘occupied’ (0) or 
Yempty' (1). 

An RRDS cannot have any index. No free space definition is 
allowed. 


Figure 9 shows a possible structure of an RRDS after loading a few 
relative records. Each slot has an RDF which includes the informa- 
tion indicating whether the slot is ‘occupied’ or ‘empty’ (see also 
section 2.6.3 on page 28). The numbers in the fields represent 
slot numbers (relative record numbers) containing records. oie 
small numbers below the fields show the length of each field. 


When adding a record and specifying a slot number which is higher 
than any slot number used so far, the data set is formatted auto- 
matically to the end of the control interval receiving the record. 


1 bebe) bop 
80 80 8 0 8 0 80 1090 3 3 3 3 3 3 A] 


8 0 


eoLepealy le eer 
80 80 80 $0 8 0 80 10 3 3 3 3 3 3 ] 


8 0 8 0 8 0 8 0 8 0 80 10 3 3 3 3 3 3 ¥ 


(CE) = empty slot n = unusable space (remaining space) 
R1-18 = RDFs (Record Definition Fields) of the corresponding slots 


QQ 
TT 


CIDF (Control Interval Definition Field) 


Figure 9. Relative record data set structure 


Chapter 2. What Is VSAM 15 


A VSAM cluster is a logical definition for a VSAM data set and has 
one or two components. | 


the data component of a VSAM cluster consists of all control areas 
containing the control intervals which contain the data records. 


The index component of a key-sequenced cluster consists of the 
index control intervals containing the index records which each 
points to the highest keys of a data control interval (see also 
section 2.4 on page 18). 


The VSAM cluster consist of the following: 


o- KSDS cluster: _ = index component 
~ data component 


° ESDS cluster: 3 _ data component 
® RRDS cluster: - data component 
A VSAM data set is always represented in a VSAM catalog by a 
cluster entry, a data entry and (for a KSDS only) an index entry. 


All parts of a multivolume data set component must reside on the 
same device type. 


| EUSABLE DATA SET 


Enhanced VSAM allows the use of VSAM data sets as Workfiles. 


A non-reusable data set may be loaded once and only once. After 
the data set is loaded, it can be read, written into, and the data 
in it can be modified. But when the data becomes obsolete, the way 


to remove it, is to use the Access Method Services command DELETE 
which deletes the data set (DELETE is described on page 61). T+ 
the data set is to be used again it must be redefined with the 
Access Method Services command DEFINE (described on page 61). 


Instead of using the DELETE - DEFINE sequence the REUSE function 
can be used. In order to specify a data set to be reusable, the 
REUSE parameter must be specified in the DEFINE 


CLUSTERIALTERNATEINDEX command (these commands are described later 
in this manual). 


A reusable data set may be a suballocated KSDS, ESDS or RRDS (See 
description on page 40) that resides on one or more volumes. 


To explain the function of a reusable data set, another VSAM term 
must be explained. As mentioned earlier (page 10) the size of a 
VSAM data set is represented by RBA values. VSAM uses a so called 
high-used RBA field to determine if a data set is empty or not.. 
After a data set is defined with a DEFINE CLUSTER command (des- 
cribed later) the ‘high-used RBA' value is zero. After any loading 
and closing the data set this field shows the offset of the last 


byte in the data set (see explanation of LISTCAT printout on page 
156). 
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In a reusable data set (i.e. a data set defined with the REUSE 
parameter) this ‘high-used RBA’ field can be reset to zero and VSAM 
can use this data set like a newly defined data set. 


The ways to ‘'reset' a reusable data set are as follows: 


1. Use the REUSE parameter in the Access Method Services command 
REPRO when reloading the data set. 


2. Specify in the ASSEMBLER user program ACB the parameter 
MACRF=RST (see macro description on page 217 and figures 47 
and 48 on pages 212 and 215). 


3. Use High Level Languages (such as PL/I or COBOL/VS) and open 
the reusable data set for OUTPUT. 


If a reusable data set is opened without specifying a ‘reset’ 
function the data set with its data is used 1ike any other 
non-reusable data set. 


When a reusable data set is opened and one of the ‘'reset' functions 
is specified, all secondary extents are unallocated and the data 
set '‘high-used RBA' is set to zero. In addition the data set is not 
Yerased' (i.e. overwritten with X'00') during a ‘reset’. 


Restrictions: 


1. KEYRANGES cannot be specified (see description on page 91). 


2. Alternate indexes (see page 29) cannot be defined over a 
cluster with the REUSE attribute. 


3. The data set cannot have more then 16 extents per volume. 


4. The data set cannot be a UNIQUE cluster (described on page 
GO). 


5. The Access Method Services command ALTER cannot be used to 
change the data set attribute from REUSE to NOREUSE or vice 


versa. 


6. Reusable data sets on 3850 (MSS) must begin on cylinucy 
boundary to prevent staging in RESET mode. 
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2.4% KSDS PRIMARY INDEX STRUCTURE 


A KSDS consists of an index (index component) and logical records 
(data component) with different data set (component) names. All 
extents of the KSDS data component must reside on the same type of 
direct access devices. The index component, however, can be placed 
on a device type different from that of the data component. 


The index for a VSAM KSDS data set contains Key values and poin- 
ters. It is built when the KSDS is initially loaded. A VSAM index 
also contains information about available space in the index 
component. | 


Although it is an internal VSAM function it should be mentioned 
that the Key in an index entry is stored ina compressed form. 
This is called key _compression (for detailed description of key 
compression see section 8.6 on page 203). For index calculations 


(see page 198) an average compressed key length of 3 can generally 
be used. 7 


In most cases a VSAM index consists of 2-3 index levels. The 
lowest level is called the sequence set. All levels above, which 
are automatically built by VSAM when necessary, are collectively 
referred to as the index set. 


In the sequence set, there is one index record per data CA. Each 
index record is designed to contain a number of index entries equal 
to the number of data CIs which fit in its CA. 


An index record (equivalent to one index control interval) is fixed 
in length, either 512, 1024, 2048 or 4096 bytes (index CI sizes are 
described on page 195)). 


Each index record contains. a pointer to an index record in the next 
lower index level or to a control interval in the data component. 


An index entry (in the index record) consists of the highest key 
associated with that CI (in compressed form), control information 
(for expanding the compressed key) and a displacement value to be 
added to the RBA of the beginning of the CA. (derived from the 
index header). The sum of which addresses the correct data CI. 


If a data set consists of more then one CA, more than one index 
sequence set level record (CI) exists. In this case VSAM automati- 
cally builds another index level (L2). Each entry in the index L2 
record points to one Sequence Set record (L1) (see figure 10). 


If the data set is that big that the index L2 record cannot hold 
all entries for all the Sequence Set records, another index L2 
record has to be built by VSAM. 


Since the highest index level can only consist of one index record, 
VSAM will build another index level (L3), etc. 


For index performance considerations see section 8.1.4 on page 19¢ 
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Figure 10 shows a logical picture of a KSDS after loading with two 
CAs, containing four CIs each. Records with 80 bytes each were 
loaded. A free space value of 20% free space in the CI and 254% in 
the CA was specified (see page 88), so 1 record (minimum = (512 * 
20%) = 102) per CI and one CI per CA (25% * 4) (CI/CA) is held free 
when loading the data set. In each CI with a length of 512 bytes 
and control fields with a total of 10 bytes, 4 data records were 
loaded (102 bytes were left free). 


The index component consists of two levels: the Index Sequence Set 
and the Index Set. 


Is 
(L2) 


Ic 
Iss 
sec 2 —an 
ne ee 
Pele [= | [al 
ee [7 [voofee] ale 
DC 


C 


free space free control intervalj|c 


La | 
| 2 | 


C = control fields (RDFs, CIDF) IS = Index Set 

DC = Data Component ISS = Index Sequence Set 
fp = pointer to free CI L1,L2 = Index Level 1 and 2 
fs = free space (FREESPACE def.) us = unused space 

IC = Index Component (IS + ISS) | 


Figure 10. Key-sequenced data set structure 
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2:5 NSERTING, EXTENDING AND DELETING OF RECORDS 


A KSDS can be defined to reserve space for later insertions when 
the data set is loaded (or sequential insertions performed). This 
reserved space is called free space. 3 ‘ 


The amount of free space in a CI and/or CA (in %) is specified in 
the FREESPACE parameter of the DEFINE CLUSTER command (see also 
page 88, and example on page 106). 


When a record must be added to aocontrol interval, records with 
keys higher than the one to be inserted are shifted to the right of 
the CI within the free space limit. As long as enough free space 
is available in this CI, there is no further data CI manipulation. 


As described in the following sections (starting section 2.6 on 
page 22) VSAM allows three types of access to insert, delete and 
extend records into a KSDS: 


e Direct Access 
@ Sequential Access | 
° Skip-sequential Access 


The Direct Access logic is described in the following paragraphs. 


Sequential Access is used for loading data sets and for insertion 
of groups) of pre-sorted records and is also called ‘Mass 
Insertion’. Mass insertion is described in detail in. section 8.8 
starting on page 207. | | 


Skip-sequential Access is described in section 2.6.1.2 on page 23. 
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The following examples illustrate the usage of free space: 

This CI is 512 bytes long. A £ree space value of 30% has been 
specified. With a fixed record length of 80 bytes, the maximum CI 
capacity is 6 records. But after loading the data set, each Cl 
contains only 4 records and 182 bytes of free space (VSAM calculat- 
ed a minimum of 153 bytes free space). 


Tels [=] «lame [pe] 


° Record 25 is to be inserted. The control interval is read into 
a VSAM buffer and records 30 and 40 are shifted to the right. 


Ce ee 


° Records 20 and 40 are to be deleted. The remaining records are 
shifted to the left if necessary and the freed space is now 
available for inserts, updates, etc. 


° Record 10 must be expanded to 148 bytes. 


30 free space|+R7|/*R*/¥*RI/* C 


R1~R? = RDFsS (Record Definition Fields) 
C = CIDF (describes free space and offset) 
* = value changed 
+ = new control block 


Note: Not one of these changes require a change in the related 
index sequence set, even if the high key record ina CI is 
deleted. 


Figure 11. Inserting, deleting and extending records 


If the record to be inserted will not fit in the control interval, 
a control interval split takes place to provide sufficient space in 
the control interval to contain the record. The control interval 
split is described in detail in section 8.5 on page 201. | 


Chapter 2. What Is VSAM 2 1 


2.6 PROCESSING OF DATA SETS 


The following request types are allowed for KSDS processing: 


add/load records 

insert records (between existing records) 
modify existing records © 

retrieve records 

extend/shorten existing records 
delete/erase records 


e©ee€¢ @ @ 


As described in the following sections the records in a KSDS can be 
processed sequentially, skip-sequentially, or directly using the 


primary Key as search argument. This is called keyed processinYa 
and it is the normal way to process a KSDS. 


Another method of processing a KSDS directly or sequentially (but 


not recommended) is addressed processing using an RBA as search 
argument (see page 26). When a split occurs, or when records are 


added, deleted or changed in size, RBAs of some records will 
change, and so addressed access is not suggested for normal use. 


One other way of processing a KSDS is control interval processing, 
which is used only for very specific applications. For further 
information see section 5.2.4 on page 74. | 


2.6.1.1 KSDS KEYED SEQUENTIAL PROCESSING 


Keyed sequential processing is used to load a KSDS and to 
retrieve, update, delete and add logical records to an existing 
KSDS. When Keyed sequential processing is used, records . can be 


processed in ascending or in descending sequence by primary key. 
When retrieving records, Key values need not be user-supplied, 
Since VSAM automatically obtains the nekt logical record in 
sequence. Following types of operations can be performed using 
keyed-sequential processing: | a | 


° Records can be processed in ascending primary key sequence. 
This is called forward processing. | 


° Records can be processed in descending primary key sequence. 
This is called previous record processing or backward proces-~ 
sing. | | 


22 VSAM PRIMER and REFERENCE 


e A mass sequential _insertion technique is used by VSAM when 
additions of contiguous records are sequenced and sequential 
processing is used. More information is included in section 
8.8 on page 207. See also section 2.6.1.6 on page 24, which 
contains an overview of keyed sequential processing logic. 


For keyed-sequential processing the index sequence set is used to 
find the next logical control interval. 


search arguments are not required or used. 


2.6.1.2 KSDS KEYED SKIP-SEQUENTIAL PROCESSING 


Keyed skip-sequential processing, is a variation of direct proces- 
Sing. It can be used for retrieval, update, addition and deletion 
operations. The logical records must be processed in ascending 
sequence without pre-positioning. Only the sequence set of the 
primary index is used for skip-sequential processing based on the 
primary key. | 7 


When a relatively small number of transactions that are in primary 
Cor alternate) key sequence and clustered in sequence are to be 
processed, skip-sequential processing can be used to retrieve the 
records directly by key. a 


Skip sequential processing can be used to avoid retrieving wth 
entire data set sequentially to process a relatively small perceii- 
tage of the total number of records, | or to avoid using direct 
retrieval.of the desired records, which causes the primary index ‘to 
be searched from the top to the bottom level for each record, but 
skip-sequential does read all sequence set records between those in 
question, therefore it is not’suggested to use skip-sequential, 
when a record from the beginning and one from the end of the data 
set has to be processed. | 


See also section 2.6.1.6 on page 24, which contains an overview of 
keyed skip-sequential processing logic. 


2.6.1.3 KSDS KEYED DIRECT PROCESSING 


With keyed direct processing records can be retrieved, updated, 
deleted and added. A Key value must be presented by the user for 
each logical record that is to be processed. For retrieval opera- 
tion, the supplied key can be the full Key, or a generic Key (the 
leftmost part of the key) which matches exactly or is greater then 
the Key of the desired record, and the record retrieved can have 
the exact or next greater key. The primary index is searched from 
the top to the bottom level to locate the requested logical record. 
See also Section 2.6.1.6 on page 24, which contains an overview of 
keyed direct processing logic. 


Chapter 2. What Is VSAM 23 


2.6.1.4 KSDS ADDRESSED DIRECT PROCESSING 


Addressed direct processing is not suggested to use for a KSDS, 
since RBA values of many records may change when a control interval 
or control area split occurs. 


2.6.1.5 KSDS CONTROL INTERVAL PROCESSING 


Control interval processing should be used only for very specific 
or unusual applications. For further information, see section 
5.2.4 on page 74. 


2.6.1.6 KSDS OVERVIEW OF KEYED PROCESSING 


The following demonstrates the three suggested types of KSDS 
access. Refer to figure 12 where records to be processed are 
marked with an asterisk '‘'*X'., 


f 


° Keyed sequential access: 


For retrieval, as Keys (search arguments) are not required 
Conly used for positioning) all 6 CIs have to be read and 
all records returned to the user, although CIs #3 and #5 do 
not contain any requested records. The Sequence Set is 
used to find the next logical control interval. 


e Keyed skip sequential access: 


The search arguments must be presented in ascending 
sequence. Here only CIs #1, #2, #4 and #6 are read. For 


each request the Sequence Set is used to find the nex: 
logical control interval and to check whether it contains 
the requested record. 


° Keyed direct access: 


For each request a search argument must be presented in any 
order, and one record (control interval) from both the 
Index Set and the Sequence Set, and also the control 
interval containing the record must be read (not if the 
appropriate Sequence Set record and/or the data control 
interval was/were already read into the buffers by tke 
previous operation and are still valid). 
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DC = Data component (data control intervals) 
IC = Index component 
IS = Index Set Chighest index level) 
ISS = Sequence Set (lowest index level) 
Figure 12.. Keyed sequential, skip-sequential, and direct proces- 
Sing. 


2-6.1.7 POSITIONING FOR A KSDS 


e Sequential processing: 


Sequential processing can be started from the beginning or 
somewhere in the middle of a data set. If processing is to 
begin in the middle of a data set positioning iS neceSSary 
before sequential operation can be performed. 


Positioning can be done in two ways: 


- execute a POINT macro instruction (see page 221) supplvin;y 
a Key as search argument. | 


as in a user ASSEMBLER program issue a 'direct' request, then 


change RPL (see page 218) with the MODCB macro (see page 
219) from ‘'direct' to 'sequential' or 'skip-sequential’. 


Chapter 2. What Is VSAM 25 


° Skip-sequential processing: 


If the first skip- sequential search: is the first access after - 
opening the data set, a direct search is initiated by VSAM to 
find the first record. From then on the index sequence set 


level will be used to find the subsequent records. If other | 


operations were performed before (like read sequential, etc.), | 
either the last position of that operation will be used as a 
starting point to search the Sequence Set records, or a re-po- 
Sitioning is necessary (see previous “paragraph "Sequential | 
processing"). , : oo 8 = 


® Direct processing (keyed): 
No positioning is necessary since each direct request will be a 
top-down search through the index and access the CI directly. 


2.6.2 ESDS PROCESSING 


The following request types are allowed for ESDS processing: 


e add/load records Conly at the end) 

° modify existing records (no record pengeh change) 

° retrieve records x 3 - 

° delete records (no erase; for ‘mark delete" see the following 
section) _ : | | | . 

Addressed sequential, addressed direct, and control interval 


processing are supported for ESDS. 


The ee two are called addressed processing and it is the normal > 
way to process an ESDS. 


No keyed processing is allowed. 


2.6.2.1 ESDS ADDRESSED SEQUENTIAL PROCESSING 


For addressed sequential processing, the RBA given by the user is. 
only used for positioning requests (see section 2.6.2.5 on page — 
27). VSAM automatically stores records in sequence of arrival and — 
retrieves them in stored ae sequence. 7 


When addressed sequential processing is used to process records in 
ascending RBA sequence, existing records can be retrieved, updated 


(but not changed in size) and marked deleted (not erased). ‘Marked | 


deleted’ means the user can modify a bit or byte ina Pecore field 
he designated as a ‘delete bit/byte' ‘ae 4 The user must provide re 
support to prevent copying these records as VSAM does not EeCOg na ee | 
this ‘delete bit/byte'. | : : : 7 


New records are only added at the end of the data set. 
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2564248 ESDS SKIP-SEQUENTIAL PROCESSING 
Skip-sequential processing is not supported for ESDS. 
2.6.2.3 ESDS ADDRESSED DIRECT PROCESSING 


Addressed direct processing by user-supplied RBAs, can be used to 
retrieve records, update their contents (but not change their size) 
and flag records to be deleted (no physical deletion). New records 
cannot be added. 


The user can obtain the RBA values of the. individual records when 
loading the data set by issuing a SHOWCB macro instruction (see 
page 219) to obtain the 'RBA' field in the RPL (Request Parameter 
List, see page 218) just used (for more information see the "DOS/VS 
Macro Reference’ manual or the 'OS/VS VSAM Programmer's Guide’ as 
described on page 2). 


2.6.2.4 ESDS CONTROL INTERVAL PROCESSING 


Control interval processing should be used only for very specific 
or unusual applications. For further information, see section 
5.2.4 on page 74. 


2.6.2.5 POSITIONING FOR AN ESDS 

° Sequential processing: 
Sequential processing can be started from the beginning or 
somewhere in the middle of a data set. If processing is to 
begin in the middle of a data set positioning 1S necessary 
before sequential operation can be performed. 


Positioning can be done in two ways: 


= execute a POINT macro instruction (see page 221) supplying 
a RBA as search argument. 


= in a user ASSEMBLER program issue a ‘direct’ request, then 
change RPL (see page 218) with the MODCB macro (see page 
219) from ‘direct’ to ‘sequential’. 
° Direct processing: 
Direct processing can be accomplished when the correct RBA for 


the record is supplied by the user as search argument (see also 
previous section 2.6.2.3). 
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2.6.3 RRDS PROCESSING 


The following request types are allowed for KSDS processing: 


add/load records | 

insert records (between existing records into an empty 'slot') 
modify existing records (no record length change) = 
deleteverase records | 


ee 


For RRDSs, Keyed-sequential, keyed-skip-sequential, keyed-direct 
and control interval processing are supported. The relative record 
number is used as an argument for keyed processing. The former 
three correspond to Keyed processing which is the normal way to 
process an RRDS. | | 


No addressed processing is allowed. 


An RRDS can be created using keyed sequential, skip-sequential, or 
keyed direct processing. 


VSAM always uses the relative record number as search argument. Et 
converts it to an RBA value and determines the control interval 
containing the requested record. If a record ina slot flagged as 
'empty' is requested, a 'no-record-found'’ condition is returned. 


A user cannot use an RBA value to address a record in an RRDS. 


A request to adda record ina slot beyond the current end of file 
indicator causes VSAM to preformat the data set from the current 
end of file up to the control interval where the new record is 
supposed to reside. Loading an RRDS with Keyed direct processing 
may result in long preformatting times if a record with a high 
number is loaded first. 


2.6.3.1 RRDS SEQUENTIAL PROCESSING 


RRDS sequential process is treated the same way as ESDS sequential 
processing (see section 2.6.2.1 on page 26) Empty slots are auto- 
matically skipped by VSAM. 


2.6.3.2 RRDS KEYED SKIP-SEQUENTIAL PROCESSING 


Basically sKkip-sequential is treated like an RRDS direct request, 
but the position is maintained. The buffer handling is treated like 
for sequential, i.e. the buffer is not written back after each 
write operation. : | : a 


Records must be in ascending sequence. 
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2.6.3.3 RRDS DIRECT PROCESSING 
An RRDS can be processed directly by supplying the relative record 
number as Key. VSAM calculates the RBA and accesses the appropriate 


record/slot. 


RRDS direct addressed processing (supplying RBAs) is not supported. 


226,374 RRDS CONTROL INTERVAL PROCESSING 
Control interval processing should be used only for very specific 
“y 


or unusual applications. For further information, see sects: 
5.2.4 on page 74. 


2.6.3.5 POSITIONING FOR AN RRDS 

e Sequential processing: 
Sequential processing can be started from the beginning or 
somewhere in the middle of a data set. If processing is to 
begin in the middle of a data set positioning is necessary 
before sequential operation can be performed. 


Positioning can be done in two ways: 


= execute a POINT macro instruction (see page 221) supplying 
a relative record number (used as Key) as search argument. 


ss in a user ASSEMBLER program issue a ‘direct’ request, then 
change RPL (see page 218) with the MODCB macro (see page 
219) from ‘direct’ to ‘sequential’ or 'skip-sequential'. 


@ Skip-sequential processing: 


No prepositioning is necessary for skKip-sequential processing 
Since it is treated like a direct request. 


° Direct processing: 


No prepositioning is required. 
Died, ALTERNATE INDEX, PATH 


Alternate indexes enable the logical records of an ESDS or of a 
KSDS (in this context called a base cluster) to be accessed sequen- 
tially and directly by more than one key £field. This eliminates 
the need to store the same data in different sequences on multiple 
data sets for the purpose of various applications, or to re-sort 
the data (see figures 13 and 14 on page 33 and 34). 
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Alternate indexes are not supported for RRDS. 


Any field in the base cluster record can be used as an alternate 
Key. It may also overlap with the primary key (in a KSDS), or with 
any other alternate Key. The alternate key field must be a conti- 
guous field with the same offset in each record (in a spanned 
record, this field must be located totally in the first control 
interval). 


Each alternate index consists of an index component anda data 
component. These two components together form an alternate index 
(abbreviated AIX) for the base cluster. Its structure is like 
KSDS. An alternate index will contain the different alternate key 
values of a certain alternate key. For every alternate key field a 


different alternate index is needed. 


The Access Method Services program allows you to define, and then 
to create alternate indexes (if BLDINDEX command is specified by 
the user). An alternate index can be defined only after its 
associated base cluster has been defined, and it can be built only 
after its base has been loaded with at least one record. 


The primary index component of a base cluster and any alternate 
index can be placed on a different device type than that of the 


base cluster data component. The primary index component and the 
alternate index need not reside on the same type of direct access 
device either. In addition, the index component of an alternate 


index can be ona different device than the data component of an 
alternate index (there is one exception for DOS/VS Cespecially for 
the device IBM 3330): should the data component of a UNIQUE KSDS 
reside on a 3330, the index component thust reside ona 3330 as 
well). 


Unlike the primary keys, which must be unique, identical alternate 
Keys may occur in more than one logical record. This allows the 
search with a given alternate key to read all base cluster records 
containing this alternate Key. 


The BLDINDEX command causes a sequential scan of the specified base 
cluster, during which alternate Key values and primary Keys (for a 
KSDS) or record RBAsS (for an ESDS) are extracted and put together 
to form alternate index records. These records are sorted by 
ascending alternate keys (no SORT program product is required). 
The alternate index records are then constructed and written. 


There may be more than one primary key/RBA per alternate Key. The 
primary Keys/RBAs will be in ascending sequence within an alternate 
index record after loading ( see figures 13 and 14 +=on page 33 and 
34). But this fact will not necessarily be true after the base 
cluster has been updated (especially the alternate Key fields) or 
new records added, as any new primary key/RBA will be inserted at 
the end of the appropriate alternate index record. 
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An alternate index is itself a KSDS. The data component of an 
alternate index is similar in physical format to the data component 
of a KSDS base cluster. The alternate key record contains system 
header information, and for a KSDS hbase cluster the alternate Key 
value (not compressed), and the primary Key field (not compressed) 
of the logical record in the base data set that contains the 
alternate Key. For an ESDS base cluster, the alternate Key record 
contains RBA values instead of primary Key values. 


The index component of an alternate index contains compressed 
alternate Keys in ascending collating sequence and is physically 
and logically structured like a primary index (see page 18). 


Alternate index maintenance can be handled by the user or automati- 
cally by VSAM. Automatic alternate index updating can be specified 
when defining the alternate index (see section 7.6.4 on page 110). 
Specifying the UPGRADE attribute for an alternate index makes it 
part of the upgrade set of alternate indexes for a given KSDS or 
ESDS. 


An alternate index can be part of the upgrade set for a KSDS or 


ESDS even though it is not explicitly used. The maximum number of 
alternate indexes that can be part of the upgrade set for a given 
KSDS or ESDS is 125. Having alternate indexes in an upgrade set 


adds processing requirements, and therefore affects performance 
when inserting or deleting records, or updating alternate Keys ina 
record in the base cluster. 


2.7.1 ALTERNATE INDEXES FOR KSDS 


Consider as an example aKSDS data set whose records contain 
customer number, address and the name of the salesman who takes the 
orders (see figure 13 on page 33). The customer number is used as 
primary Key value. If the company plans a special sale ina city, 
they may want to write a note to all customers living in this area. 
Without having an alternate index, the whole data set must be read 
and all records containing the name of the city must be extracted. 
Or, 1i£ they want a summary of all the customers served by a parti- 
cular salesman, the whole data set must be read to find all records 
with the salesman's name. However both of these requirements could 
be easily met by using alternate indexes (section 2.7.5 on prge 36 
explains how to access the base cluster records via the two alter- 
nate indexes). 


Since using an alternate index is time-consuming (create, upgrade, 
etc.), it should only be considered for frequently used applica- 
tions. Otherwise sequentially extracting and sorting records, 
running BLDINDEX with the REUSE option may be faster (the reusabil- 
ity of a data set must be specified when the data set is defined). 
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2.7.2 ALTERNATE INDEXES FOR ESDS 


Normally the only way to access an ESDS directly is to store the 
RBA value of each record ina separate user data set. The RBA 
value can be obtained by issuing a SHOWCB macro instruction (see 
page 219) to obtain the 'RBA' field in the RPL (Request Parameter 
List; see page 218) just used. 


One or more alternate indexes can be built for an existing ESDS 
when the record contains a field which can be used as alternate key 
value. An alternate index for an ESDS has the same structure as an 
alternate index for a KSDS base cluster. The only difference is 
that the alternate index records contain RBA values (4 bytes) 
instead of primary key values (see figure 14 on page 34). | 


2.7.3 EXAMPLES FOR ALTERNATE INDEXES 


Figures 13 and 14 contain the structure of two alternate indexes 
connected to a KSDS and an ESDS respectively. : 


For the data sets, the following is assumed: 


- The base cluster consists of 1 control area 
- The control area contains 3 control intervals 
= The record length in the base cluster is 320 bytes (X'140') 
= The control interval sizes (CISIZE) for base cluster and 
alternate indexes were defined as follows: _ 
= Index control intervals = 512 bytes 
7 Data control intervals = 1024 bytes 


The JCL statements and the Access Method Services commands to 
create a structure like this (DEFINE, BLDINDEX etc.) are contained 
in chapter 7.0. 


Notes to figure 13 and 14: 


In figure 13 and 14 the control £fields (RDFs, CIDF) and the unused 
Space at: the end of each CI are not shown. The records in the 
alternate indexes also contain header information, and the records 
are shorter than the records in the base cluster, so actually mczre 
records can be placed into a control interval. : 


VSAM places logical records in CI format, ensuring that (with the 
exception of spanned processing) each CI starts with the first byte 
of the logical record. In this example in each base cluster 
control interval 54 bytes (1024 - 3*320 - 10 bytes control informa- 
tion) remain unused. | 


Notes to figure 14: 


The RBAS are always written as a full word binary integer (the RBA 
values in the figure were shortened due to limited space). 
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I Mike|Tom unused 
ALTERNATE 
INDEX 1 
D 
1 
! Tom 10 41 free 
. 
i] 
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’ 
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{ 
Tr ! unused 
, 
{ 
ALTERNATE 
INDEX 2 
{ 
{ " 
(CITY) A-City 10 15 391B-City 12 36/E-City 23; us 
D 
| 
| 
{ 
f 
1 
1 
| 
{ 
a | 
} 
1 
t 
' 
§ 
—— unused 
BASE 
CLUSTER 
(CUSTOMER) 
D 


39 A-City Fred|41 G-City Tom £free 


us = unused space 
I = Index component 
D = Data component 


Figure 13. Alternate indexes with KSDS base cluster 
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rs ae 


ALTERNATE 
INDEX 1 | 
(SALESMAN) Ben 400/Bi11 000 Fred 140 540 940IMike 680 
: 
ALTERNATE 
INDEX 2 
D | : 
BASE RBA - — X'140" X'280! X'3BF! 
CLUSTER | | . 
36 B-City Bill|15 A-City Frea|10 A-City Tom 
(CUSTOMER) . 
RBA X'4O00! X'54Q' x'680! X' TBF! 
D 21 F-City Ben [23 E-City Fred|12 B-City Mike 
RBA X'800' | | X'94O! X'ASO! 


41 G-City Tom |39 A-City Fred| . unused 


IT = Index component 
D = Data component 


Note: See notes on page 32. 


Figure 14. Alternate indexes with ESDS base cluster 
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Before accessing a KSDS or ESDS (from now on both types of data set 
Will be simply called the base cluster) via an alternate index, a 
path must be defined. AR path is the means by which a base cluster 
is accessed by way of its alternate indexes. A path is defined and 
named using the Access Method Services program. At least one path 
must be defined for each of the alternate indexes through which the 
base cluster is to be accessed. When a given alternate index is to 
be used to process a base cluster, the associated path must be 

specified in an OPEN macro instruction. This causes both the base 
cluster and the alternate index to be opened. 


If a path connects a base cluster with an alternate index belonging 
to the upgrade set (see page 31) of this base cluster, the parame- 
ter UPDATE/NOUPDATE can be defined for the path to allow/prevent 
VSAM to update the alternate index, when base cluster records are 
inserted, deleted or modified (if the alternate key changes). See 
also description on page 110. 


In the following example the data sets were defined as follows: 
ALTERNATE INDEX 1 with the name SALESMAN, ALTERNATE INDEX 2 with 
CITY, and the BASE CLUSTER with. CUSTOMER. Then PATH 1 was defined 
With the name SALECUST, and PATH 2 with CITYCUST (the JCL and 
control statements for this example are included in section 7.6.4 
starting on page 111). _ 


ALTERNATE 


ALTERNATE 
INDEX 1 | INDEX 2 
(SALESMAN) (CITY) 
PATH 1 \ PATH 2 
(CITYCUST) 


(SALECUST) 


OO / 
,. en #4 


BASE 


CLUSTER 
(CUSTOMER) 


- Figure 15. Alternate Indexes with Path 
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2.7.5 ACCESS TO BASE CLUSTER AND ALTERNATE INDEX W/WO PATH 


The following simple examples show the function of paths and 
alternate indexes to accessing the base cluster (use figures 13 and 
~=6415 as a reference). The records read by. each GET can be optionaliys 
oeaser by VSAM CRPL OPTCD=MVE) into the user's program input aree. 


All accesses are seuuen ees with seare a arqument AIX is th 
abbreviation for Alternate Index. | 


° Access the base cluster directly: 


OPEN base cluster CUSTOMER 


GET 3 ——————+ | [1 A-City Tom | 
GET 3 ————_> _| 12 B-City Mike 


e Access the base cluster via AIX1: 


OPEN path SALECUST 


GET eee {21 F-City Ben 
GET aa RR 36 B-City Bill 


° Access the base cluster via AIX2: 


OPEN path CITYCUST 


GET  ———-+ 10 A-City Tom | | 
GET rrr 15 A-City Fred 


° “Opening AIX1 by its data set name 
OPEN alternate index SALESMAN 


GET 3 ———+ [Ben 21 
GET) 3=———____+>_ Bill 36 
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° Opening AIX2 by its data set name 


OPEN alternate index CITY 


GET eee eae A-City 10 15 39 
GET SF as B-City 12 36 


The following examples show the effect of the UPGRADE/NOUPGRADE 
attribute when inserting records into a KSDS cluster or into its 
alternate index (use figure 13 on page 33 as reference). When 
accessing the base cluster and the alternate index via a path, it 
is assumed the path was defined with the UPDATE attribute, which 
allows automatic updating of the alternate indexes if necessary. 


Example 1: Insert Record ‘40 G-City Bill’ into base cluster 
CUSTOMER. 


e Access the base cluster CUSTOMER directly or with a path 
(UPGRADE defined for AIXK1 and AIX2) 


OPEN base cl. CUSTOMER (VSAM opens also AIX1,AIX2) (*='4O') 
or OPEN path SALECUST (VSAM opens base cl.,AIX1,AIX2) (*='Bill') 
or OPEN path CITYCUST (VSAM opens base cl.,AIX1,AIX2) (*='G-City') 
C'*X' is the search argument used for the insert) 


PUT '4H0O0 G-City Bill' * update of base cluster, AIX1 and AIX2. 


Base before 
insert 39 A-City Fred}|41 G-City Tom free 


Base after : : 
insert 39 A-City Fred|40 G-City Billj|41 G-City Tom 


AIX1 before 

insert Ben 211Bill 36/Fred 15 23 39]Mike 12 us 
AIX1 after 

insert Ben 21]/Bill 36 40]/]Fred 15 23 39]Mike 12] us 


AIX2 before 

after F-City 2113G-City 41 free 
AIX2 after — : 

insert F-City 211]G-City 41 40 free 
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Example 2: Change Record '21 F-City Ben' into '21 G-City Ben'. 


Access the base cluster CUSTOMER directly (UPGRADE defined for 

AIX1 and AIX2) oe 3 7 

OPEN base cl. CUSTOMER (VSAM opens also AIX1, AIX2) (* = '21"') 
('*" is the search argument used for the insert) 


GET '21' | (this is a GET UPDATE to change a record) 


modify the record (in the user input area) 


PUT '21 G-City Ben' (this is a PUT UPDATE to change the red). 
: As a result the base cluster and AIxX2 is updated 
(AIX1 is not updated, as Ben still points to 21). 


Base before 
modification 


) 21 F-City Ben |23 E-City Fred|36 B-City Bill 
or update , : , : 
Base after 7 — 
modification 21 G-City Ben |23 E-City Fred{36 B-City Bill 
or update : . 


ALX2 before , ) " 
modification F-City 21)G-City 41 40 free 


or update 
AIX2 after : — : 
or update : : 


Note: The pointer (keys or RBAS) in an alternate index record 
is always added at the end of the record andis not sorted 
between the existing pointers. 


Anne AP ea UPDATE RESTRICTIONS FOR BASE CLUSTER AND AIX 


All data fields in the base cluster may be changed without restric- 
tion. When changing fields containing either the base key or an 
alternate key, the following restrictions apply: 


® 
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the base key (key of the base cluster index) cannot be changed, 


regardless of which index is used for access. | 

an alternate key cannot be changed if the GET for UPDATE was 
done through the alternate index, 4 | 

an alternate key can be changed if the GET for UPDATE was done 
through the base cluster. 
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2.8 VSAM DATA SET COMPARISON 


Figure 16 shows the differences between the three VSAM data set 
organizations. For further details see previous sections in 
chapter 2.0. 


Function/Structure KSDS | spss 


Access is: 


fixed 
Record format: variable 
| spanned 


used to: 


Alternate Index : yes yes 
Reusable File : yes,if no AIX]yes,if no AlXlyes 


1 


arrival seq. 


direct by 
RBA 


direct by 
Key or RBA 


direct by 
rel.record no 


fixed 
variable 
spanned 


at specified 


Deletion of a KSDS record results in physically adjusting 
logical records within a data CI. 


An attempt to insert a record later: 


* with the same Key, will be added back into the CI, at the 
Same place provided no other changes have occurred in the CI. 

* with a key within the range of the CI will be added to the 
CI, utilizing the space made available by the previous 
deletion provided there is space for the logical record (Card 
additional RDFs, if required). ee 


Deletion of an RRDS record results in that "slot's" data being 
set to binary zeros and its control fields being set to reflect 
it is 'not present'. Reuse of this space is determined by the 
user in selecting the relative record number of this slot for 
addition of a record. | 


Figure 16. VSAM data sets comparison. 
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2.9 VSAM DATA SPACES 


VSAM data sets can coexist on the same disk with nonVSAM data sets. 
Space defined ona volume for exclusive use of VSAM is called a 
VSAM data space (for VSAM ownership concept see section 2.10 on 
page 43). In OS/VS a VSAM data space can consist of a maximum of 
16 extents on a volume which need not be contiguous (no restriction 
in DOS/VS). ‘A volume can contain multiple data spaces. The 
maximum size of a data space is one volume. Several data spaces on 
more than one volume may be treated logically as one data space 
(e.g. for suballocated multivolume data sets). 


VSAM uses two different data spaces: 


° The suballocatable data space 
° The unique data space 


A suballocatable data space can contain one or more data sets anda 
data set can occupy one or more suballocatable data spaces on one 
or more volumes. A suballocatable data space is created by an 
Access Method Services command DEFINE SPACE ox DEFINE 
MASTERCATALOG/USERCATALOG (see chapter 7.0 later in this manual). 
All suballocatable data spaces on one volume are treated as one 
logical space, and it is possible to delete all empty suballocata- 
ble data spaces on a volume together. Individual suballocatable 
data spaces can not be deleted (see also section 2.9.2 on page 43). 


A VSAM cluster in a suballocatable data space is called a suballo- 
cated cluster or a suballocated data set. 


In this manual the expression 'VSAM data space/set’' usually means a 
suballocatable data space or a suballocated data set. 


A unigue data space (also called non-suballocatable data space 
contains only one data set. This data set occupies only one 
non-suballocatable data space on a volume (with up to 16 extents 
(OS/VS only)), but multiple volumes can be used for this data set. 
A unique data space is automatically built when a cluster or 
alternate index is defined with the UNIQUE attribute (see page 98). 
DOS/VS users must specify a space value in the EXTENT job control 
statement (not in an Access Method Services parameter), Since a 
unique data set occupies its own VSAM data space; the definition is 
Similar to a DEFINE SPACE command (see DOS/VS notes below). 


A VSAM cluster/vdata set in a non-suballocatable space is callec a 
unique cluster or unique data set. 


Unique data spaces cannot be shared with other VSAM data sets. 


VSAM data Spaces cannot be shared with nonVSAM data sets. 
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DOS/VS notes to unique clusters: 


A data space or a unique cluster can not be extended (no DADSM in 
DOS/VS). A unique cluster can not be defined as first VSAM object 
on a volume in a recoverable catalog (see page 250). 


Figure 17 shows examples for volumes containing a VSAM user catalog 
CUSER.CAT.ONE) and data spaces. 


SPACEs 1-4 are suballocatable data spaces created with DEFINE 
SPACE. The data set VSAM.UN2 was created with DEFINE CLUSTER with 
the parameter UNIQUE. 


The VSAM user catalog USER.CAT.ONE contains information about the 
VSAM data spaces and the VSAM unique data set/data space. In OS/VS 
also the NONVSAM data sets could be cataloged and accessed via the 
VSAM user catalog. 


SPACE 2 


This is a volume 

with a VSAM cata- 
log, 1 VSAM sub- 

allocatable data 

space, and 1 NON- 
VSAM data set. 


This 18 a volume 
using the whole 
volume as one VSAM 
suballocatable 
data space. 


Figure 17. VSAM data spaces 


This is a volume 
with 1 VSAM unique 
data space, 2 VSAM 
suballocatable 
data spaces, and 1 
NONVSAM data set. 
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The following is a list of advantages for the two types of alloca- 
tion: _ sys o ce ah Sy | 
Advantages of SUBALLOCATION: 


1. Since it is the default, there is no need to. specify it on an 
Access Method Services DEFINE command. 


2. If the suballocated cluster is ona different volume from ee: 


owning catalog, it is possible to DELETE the cluster without 
the cluster's volume being mounted (if a nonrecoverable — 
catalog is used). This is because all the information which. 
needs to be changed by the DELETE is in the catalog. © 


3. The REUSE attribute, which allows the Enhanced VSAM user to. 
reload VSAM clusters without the need for DELETE/DEFINE, is 
only supported for SUBALLOCATION oe Mn ee | 


4. DOS/VS: when using suballocatable cluster, VSAM space manage- 
ment allows dynamic space INanagement otherwise not supported 
in DOS/VS. No EXTENT information is needed - in JCL to specify 
begin and end of cluster. 


OS/VS: VSAM Space management tries harder than DADSM to avoid 
fragmentation. When looking for a place to put a suballocat- 


ed cluster, VSAM will try to find the smallest contiguous 


amount of free space which satisfies the cluster's primary 
allocation requirement, even if a more suitable. allocation is) 
possible elsewhere on the volume. | 


Advantages of UNIQUE: 


1. There is only one VSAM cluster component per VTOC entry, with 
the possibility of making VTOC names the same as cluster | 
component names. The organization of handling DASD space is 
the same as for nonVSAM data sets. VTOC related ‘emergency’ 
operations, such as SCRATCH and Zapping of password bits, can 
be isolated to one VSAM cluster component. >= 


2. On a volume with a large amount of VSAM space and a large 
number of clusters, use of UNIQUE allocation may result in 
better performance for DEFINE. This is because VSAM space 
Management expends a lot more energy in making the best 
possible fit, ‘for the DEFINE request (in DOS/VS EXTENT. 
information for begin and end of data set must be specified 
in JCL, no VSAM space management needed). This may result in 
high CPU times and many I/0 operations to the catalog for 
suballocated DEFINEs. | oo | . 
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2.9.2 VSAM DATA SPACE AND CLUSTER NAMES 


A VSAM data space defined With DEFINE MASTER/USERCATALOG or DEFINE 
SPACE (see section 7.3 and following sections starting on page 100) 
has no NAME parameter and can therefore not individually be delet- 
ed. 


A unique cluster should be:‘named with meaningful names for each 
CLUSTER, DATA and INDEX (KSDS or Alternate Index) to identify the 
components on a LISTVTOC or a LISTCAT list (see printout examples 
later in this manual). 


AR suballocatable cluster should be named with meaningful names for 
CLUSTER, DATA and INDEX (KSDS or Alternate Index) to identify the 
components on a LISTCAT list (see printout examples later in this 
Nanual). 


The following is an example on how the components could be named 
for the cluster X.PAYROL: 


Cluster : X.PAYROL 
Data > X.PAYROL.D 
Index >: X. PAYROL.I 


The NAME parameter is described in detail in section 7.2.5 on page 
93. 


2.10 VSAM OWNERSHIP CONCEPT 


The concept of VSAM volume ownership is illustrated by the £follouw- 
ing rules: 


e An indefinite number of user catalogs can be connected to the 
master catalog. 

e A user catalog can be connected to more than one master catalog 
Cin different systems). 

e User catalogs can not be cataloged in other user catalogs (if a 


master catalog with user catalog connector entries is used as a 

user catalog, its user catalog connector entries are not used). 

A volume containing a catalog is owned by that catalog only. 

A volume may only belong to one catalog. 

A catalog can own more than one volume. 

A VSAM data set must be cataloged (defined) in the same catalog 

which owns the data set's volumes. This restriction does not 

apply to nonVSAM data sets, which can be on any volume, and 

cataloged in more than one VSAM catalog and/or CVOLS (MVS 

only). 

e MVS CVOLS can only be cataloged in the master catalog. 

° VSAM ownership can only be relinquished with DELETE SPACE or 
DELETE CATALOG Calso with ALTER REMOVEVOLUMES and IKQVDU 
(DOS/VS) (described later)). | 
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2.10.1 THE VSAM ‘OWNERSHIP BIT' 


VSAM ownership of a volume is controlled by the VSAM ownership bit. 
If this bit is ON, the volume is owned by a VSAM catalog. There is 
no indication which catalog owns the volume. When a catalog 
attempts to allocate space on a volume (by means of DOS/VS system 
routines or OS-DADSM routines), the following sequence is started. 


The VSAM ownership bit is bit 0 in byte 84 (X'54') in the F4H-DS7B 
(Label) (see section A.2.2 on page 246 note 4). | 


ownership bit 
examined 


set bit 
ON 


| allocate 
space 


allocate 


Space 


no space 
allocation 


Figure 18. VSAM ownership concept 
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2.10.2 THE VSAM ‘DATA SET SECURITY BIT' 


When a VSAM catalog, A VSAM space, or a UNIQUE VSAM data set is 


allocated on a DASD volume a F1-DSCB (Label) is written into the 
VTOC. 


To protect this VSAM object from being accessed by other access 
methods the 'data set security bit', bit 3 in byte 93 (X'5D') is 
set ON (see section A.2.2, page 246 notes 10 and 14). In OS/VS 
systems the ‘data set security bit’ is also called and used as 
"OS/VS password protection bit’ (not to be mixed up with the VSAM 
password protection). 


7 we VSAM SPACE ALLOCATION 


In DOS/VS, VSAM routines are used to allocate space for catal’.s5 
and data spaces (JCL EXTENT values necessary), and to suballocate 


space for VSAM data sets ina suballocatable space (no JCL EXTENT 
values necessary). 


In OS/VS1 and OS/VS2 (SVS and MVS), VSAM catalog/DADSM routines, 
instead of OS/VS catalog and DADSM routines, are used to process 
the catalog and to allocate space on VSAM catalog and data set 
volumes. VSAM routines are used to allocate space ina suballocat- 
able data space. 


There are five major Access Method Services commands (see command 
overview starting in section 4.0 on page 57) which cause an attempt 
to allocate space. The table below shows these five commands and 
the space management functions which occur when these 5 commands 
are executed and an attempt is made to allocate space ona volume 
(see also description of VTOC on page 245). 
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DEFINE} DEFINE 
CLUSTER| CLUSTER 
UNIQUE;|SUBALL. 


DEFINE 
SPACE 
CANDID. 


Poe foe foe foe fo. 


* indicates that the function takes place for the command. 


DEFINE| DEFINE 
SPACE 


POSSIBLE 
FUNCTIONS 


CATALOG 


test ownership bit 
| for OFF 


| set ownership bit ON 


create a volume entry 


in catalog 


DOS/VS VSAM routines 
(EXTENT value req.) 

or OS/DADSM routines 
allocate space from 

disk space and write 
F1-DSCB (Label) with 
X'10' in offset X'5D' 
(VSAM protection bit) 


DOS/VS VSAM routines 
or OS/VSAM routines 
allocate the space 

from VSAM data space 


1 this function takes place only when this is the first VSAM 
allocation on this volume. 


2 For a nonrecoverable catalog no space is allocated and no F1 
DSCB is written. In OS/VS if the catalog is recoverable, a 
data space with a primary and secondary allocation of 1 
cylinder is allocated by OS/VS DADSM on the same volume as 
the data space to contain the CRA and a F1-DSCB is written 
for it Cin DOS/VS this command is not allowed for a recovera- 
ble catalog). 


%* Two F1 DSCBs (Labels) are written one for the data component 
and the second for the index component of the cluster (in 
DOS/VS uSing a recoverable catalog, the volume must already 
be owned by that catalog, before executing this command). 


Figure 19. VSAM space allocation 
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3.90 CATALOG CONSIDERATIONS 


3.1 CATALOG PHILOSOPHY 


All VSAM data sets must be cataloged in a VSAM catalog. 


Information required to process a VSAM data set, such as its 
location and physical characteristics, is contained in the VSAM 
catalog. 


There must be one VSAM master catalog for a DOS/VS or OS/VS system 
which is planned to use VSAM. 


In MVS the VSAM master catalog is the standard system catalog. 


Note that a VSAM master catalog cannot be stored on a 3850 mass 
storage volume. 


Besides the VSAM master catalog a theoretical unlimited number of 
VSAM user catalogs can be created (with Access Method Services) and 
used. VSAM user catalogs are optional and have the same structure 
as the VSAM master catalog. 


VSAM user catalogs should be used to reduce the size of the VSAM 
master catalog (to reduce catalog processing time), minimize the 
effect of a damaged master catalog, and make VSAM data sets porta- 
ble from one system to another (a pack containing a VSAM user 
catalog and its VSAM data sets can easily be moved from one system 
to the other without loading or reloading the data sets which is a 
time consuming operation; only the user catalog must be connected 
to the other VSAM master catalog with Access Method Services. 


Each catalog is an individual or special form of Key sequenced data 
set. Each VSAM user catalog has a connecting pointer entry in the 
VSAM master catalog. Each VSAM data set is cataloged either in the 
VSAM master catalog or in one VSAM user catalog, but not both. 


All VSAM data sets on the same volume must be cataloged in the Saire 
VSAM catalog. Then, all VSAM data spaces (suballocatable or 
unique) on the same volume belong to the same catalog (because of 
this, users who share avolume must also share the catalog). 
Duplicate data set names in the same VSAM catalog are not permitted 
but a given data set name can appear in more than one VSAM catalog. 


DOS/VS does allow nonVSAM entries ina VSAM catalog, but makes no 
use of these entries (non-VSAM entries cannot be defined under 
DOS/VS when uSing a recoverable catalog). | 


In OS/VS nonvVsAM data sets can also be cataloged in a VSAM catalog. 


In MVS, a generation data group can also be cataloged in a VSAM 
catalog. 
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Figure 20 shows a possible structure of VSAM environment, consist- 
ing of the VSAM master catalog (VSAM.MCAT) and two VSAM user 
catalogs. ; 


The master catalog owns volume SYSRES (the catalog volume) and 
volume VOLOO4 with the VSAM data set VSAM.STATUS on it. 


The master catalog also contains user catalog connector entries 
pointing to USER.CAT.ONE and USER.CAT.TWO. 


VSAM user catalog USER.CAT.ONE ‘owns’ volume VOL001 and VOL002 
containing the VSAM data sets PAYROLL.F, EMPLOYEE.E, and INVOICE. 


VSAM user catalog USER.CAT.TWO ‘owns' volume VOL003 containing the 
VSAM data set NEWCUST.. 


Figure 20. VSAM catalogs 
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3.2 CATALOG STRUCTURE 


The following is tp2 catalog layout of the user catalog, which is 


defined in section 7.4 on page 102. For further VTOC information 
see printout and explanation of the VTOC in section A.2.2 on page 
245. The CRA (catalog recovery area) is explained on page 250. 


F1: Z29999994.VSAMDSPC.T.. X'6D'-'70! X¥'00010000' 


VTOC Be Ss eh dt ee eee eee es K$5 =" 56" x*0037"" 
CYL HEAD 
1 004 
Low-Keyrange (30 Tracks) 
(20 data tracks + 10 index sequence set tracks) 
2 OB4 
Index (3 tracks) 
2 OFZ 
High-Keyrange (3 tracks) 
2 114 
CRA €1 cylinder) 
Notes: 


1 The CRA and its pointer in the F4Y DSCB are only included 
for a recoverable VSAM catalog (a printout of a F4 DSCB is 
shown on page 245). 


X¥'0037' ais the relative track number where the CRA starts. 
The calculation can be done as follows: 


X¥'0037' = 55 = 38 + 17 = Cyl 2 + 17 CX'11') tracks 
* The starting and ending values for the catalog are 


extracted from LISTCAT ALL output as explained and shown 
in section 7.9.2.1 on page 148. 


Figure 21. VSAM catalog allocation 
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A VSAM catalog is a special KSDS, and consists of an index anda 
data component. The data component, however, consists o£ two 
parts: Low-Keyrange and High-Keyrange (see detailed description of 
normal Keyranges in section A.1.1 on page 241 and section A.1.2 on 
page 241). | a ys | 


The catalog Keyranges are used in a different way then normal 
Keyranges (it is actually a design philosophy; see also comments on 
page 242). The splitting of the data component into High-kKeyrange 


and Low-Keyrange and placing the index between is only used ina 
catalog KSDS. | 


When defining a catalog, the size of the entire data component and 
the size of the index can be specified, but the size of the index 


component will always be one so-called ‘allocation unit’ Cone 
control area) * which is three or five tracks (allocation unit sizes 
are described on page 249). One allocation unit is one control 
area. 


The defined data component size is automatically rounded down into 
an integer number of allocation units. Then 10% Cin DOS/VS Rel. 34 
20%) (minimum 1 allocation unit) is used for the High-Keyrange and 
the rest for Low-Keyrange. 


To improve the performance, the index component is placed between 
the Low-Keyrange and the High-Keyrange, and the IMBED function (see 
description on page 89) is always used for a VSAM catalog. 


3.2.1 CATALOG CONTENTS 


The following information is recorded in ad records for a VSAM 
data set: . 


° Device type and volume serial numbers of volumes containing the 
data set. | 

e Location of the extents of the data set and secondary alloca- 
tions, if any. 

° Attributes of the data set, such as control interval size, 


physical record size, number of control intervals ina control 
area, location of the primary Key field for a KSDS, etc. 


° Statistics, such as the number of insertions, updates, retriev- 
als, splits, etc. 

° Password protection information. 

e An indication of the connection between data sets and their 


indexes): the index and data components of a KSDS; the index 
and data components of an alternate index; the alternate index 
and base cluster of a path; and an alternate index and upgrade 
set and its base cluster. | | 

@ Historic information, such as creation and expiration dates, 

owner identification, etc. 
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A VSAM catalog also contains information regarding the location of 
data spaces and available space on volumes that contain VSAM data 
sets. Therefore, a volume containing a VSAM data set need not ke 
mounted in order to determine whether it contains available Spacz 
(but if it is to take any of that space and the catalog is recover- 
able the owned volume in question must be mounted). 


3.2.1.1 CATALOG ENTRY TYPES 


Several types of entries are used in a VSAM catalog to describe the 
various objects the catalog describes (data sets, available space, 
Otess. 


The entry types are as follows (their entry types are included in 
parenthesis): 


° Alias (MVS only)(X) 

° Alternate index 
- Alternate index (G6) 
= Data component (D) 
= Index component (TI) 
= Upgrade set (Y) 

e Catalog control record (L) 

e Cluster 
- Data set cluster (C) 
= Data component (D) 
= Index component (KSDS only) (I) 


e Extension record (for all records,except the volume record)(E) 

e Free record (F) | 

e Generation data group (MVS only) (B) 

e NonvVSAM (COS/VS only),(Ccan be defined in DOS/VS (not recoverable 
catalog)) (A) | 

° Path (R) 

e Self-describing entries (see page 242) (no entry type) 

° User catalog (used in master catalog only) (U) 

° Volume (contains volume and space information) (V) 

‘ Volume extension record (W) 


Aogiven data set may require more than one entry type for its 
description, plus extension entries when the data set is extended 
and/or various volumes are used. An ESDS, for example, requires a 
cluster and data component entry. 


3.2.1.2 CATALOG SHARING 


A master or user catalog in one VS1 or VS2 operating system can be 
shared with another VS1 or VS2 operating system as a master or user 
catalog with one exception: a master catalog in one VS2 operating 
system can be shared with another VS2 system only as a user catalog 
(not as a master catalog). Catalog management routines control this 
sharing. 
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No sharing of master or user catalogs is supported under two or. 
more DOS/VS systems simultaneously. Nevertheless, read-only 
sharing of the catalogs is pessible. Therefore no changes of the 
data sets is allowed, which may change the content of the catalog. — 


3.3 VSAM PASSWORDS 


An expanded password protection facility is supported for VSAM. 
Optionally, passwords can be defined for clusters, cluster compo- 
nents (data component and index component), alternate indexes and 
components, paths, and VSAM catalogs. VSAM passwords are kept ix 
VSAM catalog entries only. The password can be supplied by the 
programmer via the ACB (a VSAM control block similar to the DOS/'S 
DTF or the OS/VS DCB used by other access methods; see description 
on page 217). | 


If password protection is indicated for a VSAM data set and the ACB 
does not specify a password (see page 55) or specifies it incor- 
rectly, the operator may supply the correct password for the data 
set to be opened. A MVS TSO user can also supply VSAM passwords. 
The number of retries allowed (frem 0 to 7) can be specified with 
the ATTEMPTS parameter (default is 2) in the DEFINE command. 


Four levels of password protection are provided: 


° LEVEL 1: MASTER PASSWORD 


Full access, which allows access to a data set, its 
indexes), and its catalog entry. Any operation (read, add, 
update, delete) can be performed on the data set and its 
catalog entry. The master password of the base KSDS must be 
specified, for example, when an alternate index is to he 
created for the base, and for other cases. ~~ 

The master password is required for altering (ALTER) and 
deleting (DELETE) VSAM data sets. 


* LEVEL 2: CONTROL INTERVAL PASSWORD (for special usage) 


Control interval access, which allows the user to reed and 
write entire control intervals using the control interval 
interface. All read, write, and update operations can be 
performed at the logical record level as well. This facili- 
ty is not provided for general use and should be reserved 
for system programmer use only. © | 


° LEVEL 3: UPDATE PASSWORD 


Update access, which allows logical records to be 
retrieved, updated, deleted, or added. 
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For the catalog the following applies: 
= DOS/VS, _VS1, SVS: Update password is required for 
defining VSAM data sets and nonVSAM data sets in VS1 
and SVS). No passwords are required in VS1 and SVS for 
altering (ALTER) and deleting (DELETE) a nonvVSAM data 
set. 


- MVS: Update password is required for defining (DEFINE) 
VSAM and nonVSAM data sets and for altering (ALTER) and 
deleting (DELETE) nonVSAM data sets (including GDGs and 
ALIASes). 


° LEVEL 4: READ PASSWORD 


Read access, which allows access to a data set for read 
operations only. Read access to the catalog entries of the 
data set (except password information) is permitted also. 
No writing is allowed. 


A password can be defined for a given VSAM data set for 
each level protection: master password, control interval 
access password, read- Write-add-delete password, and 
read-only password. When multiple passwords are defined rer 
a data set, the password given when the data set is openes 
establishes the level of protection to be in effect fcr 
this OPEN. 


Authorization to process a VSAM data set can be supplemented by a 
user-written security authorization routine. 


If supplied, such a routine must reside in the following library: 
° DOS/VS : System CIL or Private CIL (Core Image Library). 


° OS/VS > SYS1.LINKLIB or in a library to be located by’ the 
system (e.g. in a JOBLIB). 


It is entered during OPEN processing after password verification 
has been performed by VSAM, unless the master access password was 
specified. A user security authorization record of up to 255 bytes 
maXimum can also be added to the catalog entry for the data set. 
This record can supply data to the user-written security authoriza- 
tion routine during its processing. For further information see 
the appropriate Access Method Services manuals as listed on page 2. 


The VSAM catalog must be password protected to support password 
protection for cluster passwords. 


If passwords are not specified on all levels, the highest level 
password is propagated to the higher levels (see figure 22). 
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The following chart shows some combinations of specified passwords 
and the passwords assigned by VSAM: | 


Passwords specified by the user 


Passwords assigned by VSAM 


Read 


Update CI Master Read Update CI Master 


Figure 22. VSAM passwords 


Passwords for catalogs are strongly recommended to revent unau- 
thorized deletion of VSAM objects (e.g. clusters data spaces #nl 


catalogs). 


In OS/VS systems the VSAM master catalog master password is 
required for volume cleanup (see page 181) and other severe 
commands. Therefore it is very important to have at _ least the VSAM 
master catalog password protected. 


Passwords can be defined using Access Method Services commands (see 
definition in sections 7.4 on page 102 and 7.6.4.11 on page 121). 


Section 3.3.1 on page 55 contains information about how to specify 
a password in a user-written program. | 
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3.3.1 HOW TO SPECIFY PASSWORDS IN A USER-WRITTEN PROGRAM 
As shown in figure 47 and 48 on pages 212 and 215 the ACB macro 


(see also description section 8.11.1.1 on page 217) contains a 
parameter: 


PASSWD=address 


,address' can be substituted by a symbolic field name pointing toa 
field (maximum length 1+8 bytes) with the following format: 


BS Password 


1 4 - 8 


B = length of the password (binary value) 


If a password is not supplied when a password protected data set is 
to be opened, the system operator is prompted to enter the pass- 
word. 


This prompting of the operator is controlled by the number of 
attempts to enter the password defined for the data set with the 
ATTEMPTS parameter (if this parameter was not specified, the 
default value ATTEMPTS=2 is assumed). 
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4.9 ACCESS METHOD SERVICES COVERVIEW OF FUNCTIONS ) 


Access Method Services consists of the following functions (com- 
mands): 


ALTER changes attributes in the VSAM catalog for previously 
defined VSAM objects. 


e BLDINDEX sorts and loads pointer information into a newly 
defined alternate index. 


° CHKLIST lists data sets, opened when a checkpoint was taken 
COS/VS only). 


e CNVTICAT converts OS/VS catalogs into VSAM catalogs (MVS only) 
(this is a very special function and is not described 
in this manual). 


° DEFINE defines VSAM objects, such as catalogs, clusters, etc. 

e DELETE deletes VSAM objects. 

e EXPORT coplies/exports a VSAM data set with related catalog 
information to a sequential data set (using the 
catalog to access the data sets). 

e EXPORTRA exports data sets with related catalog information, 
and nonVSAM, GDG, and Alias catalog entries (using the 


catalog recovery area to access the data sets). 


° IMPORT imports and reorganizes a VSAM data set, Which was 
previously exported by EXPORT. . 


° IMPORTRA imports and reorganizges data sets and imports VSAM 
catalog entries, which were previously exported by 
EXPORTRA. 


° LISTCAT lists VSAM catalog information. 


e LISTCRA lists and optionally compares the catalog recovery 
area information with the the catalog records. 


° PRINT prints contents of ISAM, SAM, or VSAM data sets. 


e REPRO loads, copies, converts, merges, reorganizes data sets 
and catalogs. 


e RESETCAT synchronizes and resets a catalog (using catalog 
recovery areas) 


e VERIFY resets catalog information for a VSAM data set, which 
was not closed in a normal way (e.g., hardware 
malfunction). | 
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The 2 ideaane: commands are used ‘to. control the execution of Access 
Method Services commands (modal commands) : pa ~ 


* IF and DO control _ sequence of execution based on values of 


condition codes issued by. ‘VSAM _ox changed by the user 


through the SET command. 


° | PARM specifies processing options to be used during execu- 
tion. ) fk gt ae: eee ee Gs 


e SET. changes or resets condition codes. 


u.1. ALTER 


This command is used to change attributes in previously defined 


catalog entries, for example to change data set. Passwords, free 


Space specifications, etc. 


See the appropriate Access Method Services. manuel “(listed on eee 


2) £f0r correct coding; an. example is also shown en pase 124. 


In figure 23 the master puecuord of entry ‘cust. is altered from WX 
to YZ. UCATO1 is the user gareled:, name. The VSAM data set VSAMOLD | 


is then renamed to VSAMNEW. 


. ‘Command coding: — 
\ VOL001 


UCATO1 


 VOLOO1 4. “ALTER: CUST. eee dane ee 
ore MRPWCYZ)- bat ot a 
UGATOU . od 8, asin i ee ae 
a, <2 ‘ALTER VSAMOLD a Ea hie 9 
CUST MPWD=YZ|  SRRREN ENS RNERERS 


CUST MPWD=WX 


VSAMOLD 


_VSAMNEW 


OLD” - oo NEW 


Figure 23. Logical function o£ ALTER _ 
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4.2 BLDINDEX 


This command is used to create (load) an alternate index for a base 
cluster. The alternate index must already be defined, and the base 
cluster must have at least one record. 


BLDINDEX reads all base cluster records and extracts the primary 
keys (for KSDS base cluster) or the RBAs (for ESDS base cluster), 
and the related alternate keys. This information is then sorted 
and loaded into the alternate index. 


See the appropriate Access Method Services manual (listed on page 
2) for correct coding; an example is also shown on page 113. 


In figure 24 CUST.ALT.IND is an alternate index for base cluster 
CUST. 


Command coding: 


VOLO02 


BLDINDEX INFILE C...) 
OUTFILEC...) 


oo 8@ @® @ 


CUST 


CUST.ALT.IND 
(empty) 


CUST.ALT.IND 
(data) 


OLD NEW 


Figure 24. Logical function of BLDINDEX 


4.3 CHKLIST (OS/VS ONLY) 


This is not a VSAM command and is not used for normal VSAM proces- 
Sing. 


During processing, a program can issue the CHKPT macro’. to record 
various information for use in restarting the program in the event 
of an error. This is called taking a checkpoint. 


The CHKLIST command lists the tape data sets which were open at the 
time the checkpoint was taken, thus identifying the tape data sets 
which need to be mounted for restart. | : 
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4u.4 DEFINE 


This command is used to create catalogs, and catalog entries for 
alternate indexes, clusters, data spaces, paths, and nonVSAM data 
sets. In MVS catalog entries for ALIASes, GDGs, and PAGESPACEsS can 
also he created. DEFINE creates the catalog entry for a VSAM 
object and allocates space for this object. 


See the appropriate Access Method Services manual (listed on page 
2) for correct coding; examples are also shown starting on page 
100. 


Figure 25 shows the definition of a userz catalog. 
UCATO2 is the new user catalog. 


Command coding: 


(NAMECUCATO2) - 
. VOLC(CVOL003) _ 
lunallocated | SPACE (CYL(20 1))- 


. re ee ee 2 


space 


OLD NEW 
Figure 25. Logical function of DEFINE USERCATALOG 


In figure 26 the KSDS cluster (C), data entry (D), and index entry 
(I) is added to UCATO2 (UCATO02 is the user catalog name) anda 
UNIQUE data space is built. | 

It is assumed the user specified the following names: CITY (clus- 
ter), CITY.D (data component), and CITY.I (index component) (see 
naming restrictions for MVS in section 7.2.5 on page 93). The 
unique space for the cluster CITY is to be allocated from the same 
volume. 


Command coding: 


DEFINE CLUSTER 7 _ 
C(NAMECCITY) - 

UCAT02 VOL(VOL003) - 
CITY.D UNIQUE — 
CITY 1 SPACE(CYL(5 1)))- 
DATA ~ 
(NAMEC(CITY.D)) - 
INDEX - 
(NAMECCITY.I)) - 


eo @ 8 © 


funallocated 
space 


OLD | | NEW 
Figure 26. Logical function of DEFINE CLUSTER 
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4.5 DELETE 


This command is used to delete catalogs and catalog entries. 


See the appropriate Access Method Services manual (listed on page 
2) for correct coding; examples are also shown starting on page 
174. 


In figure 27 the cluster entry with its component entries is 
deleted from UCATO2. The allocated UNIQUE space is freed to be 
used by the system. 


Command coding: 


DELETE CLUSTER - 


C(NAMEC(CITY) - 
UCATO2 VOL(VOLO003) = 
D: CITY.D UNIQUE ... ) 


TI: CiITy..1 
C: City 


OLD NEW 


unallocated 
space 


Figure 27. Logical function of DELETE 


4.6 EXPORT/IMPORT 


These commands are used to unload/reload VSAM data sets for backup 
and/or transportation. 


The EXPORT command has, among others, two important options: 
TEMPORARY | PERMANENT. EXPORT PERMANENT unloads the data set and 
deletes the entries from the catalog. EXPORT TEMPORARY produces an 
unloaded copy of the data set, and marks the catalog entry, to show 
that a temporary copy exists. In the unloaded format, the data set 
1s not accessible. | 
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EXPORT uses the VSAM catalog to copy all related information such 
as cluster entry, data entry, and index entry (for KSDS only) from 
the catalog to the target data set, a SAM VBS data set (the user 
allocated via JCL). : | | 


IMPORT redefines and reloads the data set. 


These commands can also be used to disconnect/reconnect a user 
catalog from/to a VSAM master catalog (if a user catalog is discon- 
nected from the master catalog by deleting its connector entry, it 
cannot be accessed from that system). No unload/reload is neces- 
sary. 3 : 


See the appropriate Access Method Services manual (listed on page 
2) for correct coding; examples are also shown starting on page 
122. | 


In figure 28 the unloaded copy of CITY contains data and catalog 
information for the data set CITY. The unloaded copy is to be 
stored on disk or tape, JCL must be specified as for any other 
nonvVSAM data. set (this is a SAM VBS data ‘$et). 


EXPORT 


(=) Command coding: 


EXPORT CITY - 
INFILE (...) - 
OUTFILE(...) - 


= c= * 


ry 
= 
ee 


Figure 28. Logical function of EXPORT to disk or tape 
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In figure 29 cluster CITY is restored by using the sequential VSAM 
backup created by a previous EXPORT. 


IMPORT 


= Command coding: 
IMPORT INFILE (C. = 


Figure 29. Logical function of IMPORT from disk or tape 


SS ad 


Y.7 EXPORTRA/IMPORTRA 


If certain data sets are no longer accessible because of damage to 
their catalog entries, and that catalog is recoverable, these data 
sets can be unloaded using the EXPORTRA command. 


In figure 30 EXPORTRA uses the CRA (catalog recovery area) and not 
the VSAM catalog to access the data set CITY to be recovered. It 
copies all related information such as cluster entry, data entry, 
and index entry from the catalog recovery area to the target data 
set (the target SAM data set is allocated by the user JCL, see 
EXPORT). 7 


In figure 31 IMPORTRA is used to reload the data set CITY and 
rebuild the corresponding catalog entries. The logical function is 
the same as for EXPORT/IMPORT without using the catalog to find thé 
data set. 


The EXPORTRA/IMPORTRA commands are also described in section A.6.3 
on page 259. | 
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EXPORTRA 


Command coding: 


EXPORTRA CRA ( ~ 
C(dname ENTRIES-— 
C(CCITY)) 0) = 
OUTFILE (¢....) 


Figure 30. Logical function of EXPORTRA to disk or tape 


IMPORTRA 


VOLO003  _> 


UCATOZ2 


= 


Command coding: 


oy 


IMPORTRA INFILE (...)- 
OUTFILE(...)- 


oe @ @ © 


Figure 31. Logical function of IMPORTRA from disk or tape 
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4.8 LISTCAT 


This command is used to list the VSAM catalog entries or parts of 


them. Tt is recommended to execute a LISTCAT command after any 
DEFINE command. Examples are shown and explained starting on page 
140. 


u.9 LISTCRA 


This command is used to: 


° List entries in the catalog recovery area (CRA) 
e Indicate mismatches (if any) between the CRA and the actual 
catalog 


° Dump the contents of the CRACs) 


Examples are shown starting on page 160. 


4.10 PRINT 


This command is used to print ISAM, SAM or VSAM data sets, or parts 
of these data sets. The printout can be obtained in hexadecimal, 
character or dump format. 


Examples are shown starting on page 109. 
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G.11 REPRO . 


This command transfers data between 2 data sets. If data are to be 
transferred into an empty data set, it always reorganizes the 
target data set. Sa ee | | | 


When copying an RRDS to a nonRRDS, empty slots are not copied. The 
slot numbers of the non-empty slots are lost. | 


When copying an RRDS to an RRDS, each non-empty slot in the source 
is copied to the same slot in the target. Empty slots are not 
copied. | | 


The different functions are: 


° Add records to the end of an ESDS 
° Copy a VSAM catalog (MVS only) (move a catalog to another disk) 


° Load/copy a VSAM data set 


TSAM: =P SAM Cbackup/funload an ISAM data set) 

ISAM ———~ VSAM (convert an ISAM data set to VSAM £format) 
SAM —— SAM (copy, e.g. tapes) : 

SAM ———* VSAM Cload a VSAM data set) | 

VSAM ——— SAM (bacKup/unload a VSAM data set 


VSAM ———~ VSAM (copy/merge data) 
e Merge records into KSDS or RRDS 


° Punch or print 
ISAM data sets 


SAM data sets 
VSAM data sets 


° Unload/reload a VSAM catalog (backup) 
'$ee the appropriate Access Method Services manual (listed on 


page 2) for correct coding; examples are also shown starting on 
page 108. 
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Load_a VSAM data set from disk, cards, or tape a 
For the following functions, different REPRO commands have to be 
used. | a | = eS | | 


Command coding: 


REPRO INFILE (...) - 
OUTFILE(...) - 


VOL007 
-PAYROLL 


Card Input 


DOS/VS card input: 


REPRO INFILE (SYSIPT) - 
OUTFILE (...) 

cards immediately > 

after the command 


VOL008 


KK. SAM. FILE 


Figure 32. Logical function o£ REPRO (load) from disk or tape 


‘Copy/convert data set fo data set 


Command coding: 


REPRO INFILE (...) - 
OUTFILE(...) ~ 
REPRO INFILE (...) - 


OUTFILEC...) © = 


eo 8 8 


- Figure 33. Logical function of REPRO (copy data) 
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Backup data to tape 


The output tape data set contains no catalog information. 


ry. | | Command coding: 
| | REPRO INFILE (...) - 
| OUTFILE(...) - 
Se ee © © @© € 


Figure 34. Logical function of REPRO Cbackup data sets/catalogs) 


4.12 VERIFY (ACCESS METHOD SERVICES) 


This command is used to ensure a catalog reflects the correct ‘high 
used RBA’ of a data set (the ‘high used RBA’ points to the last 
byte used in the VSAM data set; see LISTCAT explanation on page 
156). It should be used after an OPEN-error caused by a previous 
system failure or an ABEND condition while updating the data set. 


VERIFY cannot be used for empty data sets (when the high-used RBA = 
0 in the catalog cluster entry). This condition will also occur 
when an ABEND or system failure occurs during the load of the data 
set with the SPEED or RECOVERY option specified (see section 7.2.8 
on page 97), or while reloading a reusable data set specifying the 
REUSE option (see page 16). 


An example is shown on page 126. 
For further explanation see also section 4.13, which describes the 
VERIFY macro. 

4.13 VERIFY (MACRO) 


There is the VERIFY macro itself, which only update the "high-used 
RBA’ in the control block structure and not in the VSAM catalog. 


The Access Method Services command VERIFY opens the data set, 
issues the VERIFY macro to update the control blocks. Access 
Method Services then issues a CLOSE macro and it is this VSAM CLOSE 
that yp eenee the VSAM catalog. 


Section 4U.12 describes the Access Method Services VERIFY command 
and not the VERIFY macro itsel£. | 
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u.i14 RESETCAT 


This command synchronizes a recoverable VSAM catalog with its 
volumes. For example i1£f£ a VSAM volume becomes inaccessible and a 
backup copy of the catalog volume is used to restore the volume to 
a previous level, the volume may be out of synchronization with its 
catalog. 


RESETCAT compares the relevant catalog entries with the entries in 
the CRA on that volume, and resets the catalog entries where 
necessary, so that the catalog is synchronized with the volumes. 


RESETCAT usage for unload/reload and device conversion is described 
on pages 254 and 259. 


See the appropriate Access Method Services manual (listed on page 
2) for correct coding; an example is also shown on page 164. 


ACCOUNT PRODUCT 


TIME.AB | INVEST | 
gil 
TIME.AB 


le 


“+— RESETCAT 


Command coding: 


RESETCAT CAT UCATO7 ae 
CRAFILES (CCVOLAO0O1 ALL) = 
CVOLA0O2 ALL) = 
(VOLA0N3 ALL) ) x 
WORKCAT (name of a second or master catalog) - 
WORKFILE Cworkfile d-name) 


Figure 35. Logical function of RESETCAT 
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RELATIONSHIP OF DATA ACCESS TO DATA ORGANIZATION 
OVERVIEW OF ACCESS METHODS OTHER THAN VSAM 


BASIC DIRECT ACCESS METHOD (BDAM) 


In the Basic Direct Access Method (BDAM), records within a data 
set are organized on direct access volumes in any manner chosen 
by the programmer. Storage and retrieval of a record is by 
relative address within the data set or a actual disk address. 
This address can be that of the desired record or a starting 
point within the data set where a search for a record, based on 
a Key supplied by the programmer, begins. Addresses are also 
used by BDAM as a starting point when seeking available space 
for new records. 


The READ/WRITE macro instructions cause the initiation of an 
input/output operation. The completion of these operations is 
tested by using synchronization macro instructions. 


BASIC INDEXED SEQUENTIAL ACCESS METHOD (BISAM) 


Sequential and direct processing are provided by the Indexed 
Sequential Access Method (ISAM). Records are maintained on DASD 
devices in control field sequence by Key. The system maintains 
a multilevel index structure that allows retrieval of any 
record by its key. Records can be added to an existing ISAM 
data set without rewriting the data set. 


The Basic Indexed Sequential Access Method (BISAM) stores and 
retrieves records randomly into or from an indexed sequential 
data set. Selective reading is performed using the READ macro 
instruction, specifying the key of the logical record to be 
retrieved. Individual records can be replaced or new records 


can be added randomly. As new records are inserted, LSAM 
performance decreases, until it becomes necessary to reorganize 
the data set. When records are deleted, the space is not 


reuseable until after the next data set reorganization. 


The READ/WRITE macro instructions cause the initiation of an 
input/output operation. The completion of these operations 15S 
tested by using synchronization macro instructions. 


BASIC PARTITIONED ACCESS METHOD C(BPAM) (COS/VS only) 


The Basic Partitioned Access Method (BPAM) is designed for 
efficient storage and retrieval of discrete sequences of data 
(members) belonging to the same data set ona direct acces 
device. Each member of the data set has a simple name. The dévrea 
set includes a directory that relates the member name with the 
address where the sequence begins. Members can be added toa 
partitioned data set as long as space is available in the 
directory and in the data set. 
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The READ/WRITE macro instructions cause the initiation of an 
input/voutput operation. The completion of these operations is 
tested by using synchronization macro instructions. 


BASIC SEQUENTIAL ACCESS METHOD (BSAM) 


The Basic Sequential Access Method (BSAM), sequentially organ- 
izes data and stores or retrieves physical blocks of data from 
tape, disk or unit record devices. The READ/WRITE macro 
instructions cause the initiation of an input/output operation. 
The completion of these operations is tested by using synchron- 
ization macro instructions. Automatic translation between 
EBCDIC and ASCII codes is provided for magnetic tape labels and 


record formats. 


DIRECT ACCESS METHOD (DAM) 
This is another name for BDAM. 
INDEXED SEQUENTIAL ACCESS METHOD (ISAM) 


The Indexed Sequential Access Method (ISAM) is comprised of the 
Basic Indexed Sequential Access Method (BISAM) and the @ueued 
Indexed Sequential Access Method (@ISAM). See the description 
of these two access methods in this section. 


QUEUED INDEXED SEQUENTIAL ACCESS METHOD (ISAM) 


The Queued Indexed Sequential Access Method (9ISAM) is used to 
create an indexed sequential data set or to retrieve and update 
records sequentially from such a data set. Synchronization of 
the program with the completion of input/output transfer, and 
record blocking/vdeblocking are automatic. QISAM is also used to 
reorganize an existing data set. 


The GET/PUT macro instructions cause the initiation of an 
input/output operation. These operations are synchronous. 


QUEUED SEQUENTIAL ACCESS METHOD (@SAM) 


In the Queued Sequential Access Method (@SAM), logical records 
are retrieved or stored as requested. The access method antici- 
pates the need for records based on their sequential order, and 
normally has the desired record in storage, ready for use, 
before the request for retrieval is issued. When writing data, 
the program normally continues as if the record had been 
written immediately, although the access method routines may 
block it with other logical records and defer the actual 
writing until the output buffer has been filled. As with BSAM, 
automatic translation between EBCDIC and ASCII codes is provid- 
ed for magnetic tape labels and record formats. 


The GET/PUT macro instructions cause the initiation of an 


input/output operation. These operations are synchronous. 
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e SEQUENTIAL ACCESS METHOD (SAM) 
The Sequential Access Method (SAM) is comprised of the Basic 
Sequential Access Method (BSAM) and the @ueued Sequential 
Access Method (@2SAM). See the description of these two access 
methods in this section. 


The following are Telecommunications Access Methods and are not 
discussed further in this manual. 


° BASIC TELECOMMUNICATIONS ACCESS METHOD (BTAM) 


° REMOTE TERMINAL ACCESS METHOD (CRTAM) 


_° TELECOMMUNICATIONS ACCESS METHOD (CTCAM) 


° VIRTUAL TELECOMMUNICATIONS ACCESS METHOD (VTAM) 


5.2 SAM VERSUS SEQUENTIAL VSAM. 


Most direct access SAM applications can be mapped into VSAM sequen- 
tial applications with reasonably good results. There are a number 
of parameters that might affect performance significantly. 


5.2.1 LOGICAL RECORD PROCESSING (ADR-ESDS) 


This method is usually a good alternative to SAM if the number of 
records per CI is small and the number of data buffers is greater 
than the minimum (for more information about buffer, see section 
8.1.5, starting on page 190). T£ the number of records per CI is 
large, the overhead per logical record may require more CPU time 
then SAM. 


9.2.2 LOGICAL RECORD PROCESSING (CKEY-RRDS) 


One of the efficient means of doing sequential accessing is by 
using an RRDS. If the records are fixed length then this is a good 
choice. It is not possible to define an alternate index over an 
RRDS. 


5.2.3 KEYED SEQUENTIAL RECORD PROCESSING (KEY-KSDS) 


This is probably the least efficient mapping of SAM into VSAM since 
at each change of CI there must be a reference to the sequence set 
buffer to locate the next CI. If a logical consolidation of 
programs can occur which might make use of the insertion capabili-~ 
ties of VSAM then the extra overhead might be worth it. Normally in 
a SAM application a file update involves both an input and an 
updated output version of the same file containing inserted records 
or updated records having length changes. In this case a single 
KSDS can take the place of both the input and output SAM files. 
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5.2.4 CONTROL INTERVAL PROCESSING 


The most efficient method of processing is control interval ‘Proces- 


Sing, but it is considered only for very special applications. 5 ae 


problem program must, however, do all ¢o£ the ier record “block= 


ing and deblocking itself. 


For applications that can deblock a control interval easily oz | 


where there is only one record per CI this is an. excellent. choice. 
In programs uSing COBOL and PL/I versions where CNV. processing is 


not supported, the user can define a userz block at least 10. bytes 
less than the CI that will be defined for the file anak process his 
own user records. This will reduce the number of VSAM logical 
records per CI to as fer as 1 depending upon the user blocksize and’ | 


CI size chosen. 


Caution should be used processing a KSDS ox RRDS ed CNV proces- 
sing and generally should be avoided by the ape ticatson REOo EMG ye: ie 


In VS1 and VS2Z@ the ICI option (Improved cI peoussoiies. (a camino. 
eter of the MACRF parameter in the ACB macro instruction) | May be 


used to further reduce CPU time for data sets. meeting the require- 


ment of ICI Processing. The data set, however, may not be extended 
or created using ICI. If ICI is used and the program is authorized 
it may also use the CFX option (a subparameter of the MACRF parame- |. 


ter in the ACB macro instruction) to page fix the control. blocks. 


The user must specify UBF (a subparameter of the MACRF parameter. in. : 
the ACB macro instruction) and page fix his user buffer “G2 CPX is + 


used. 


5.3 BDAM VERSUS DIRECT ESDS AND RRDS 


BDAM data sets with fixed length biecite ean be mapped into VSAM | 


with fixed length records giving excellent results. 


Each fixed length block in BDAM becomes a Tegacey, iscond in VSAM. 
The dummy BDAM blocks become empty record slots, (if a VSAM RRDS is 


used) and the KEY and DATA portions of the BDAM block can be- 


combined into a single record entry) in an ESDS or RRDS. 


Because Keyed BDAM has an unblocked format | and VSAM has a blocked 


format there is potentially much better space utilization in VSAM. 
As a result the number of cylinders and consequently. the average 


seek time is generally less for an ESDS or RRDS than for BDAM. A 
read by Key in BDAM causes the channel and the device to be busy _ 
until the block is found, resulting in high channel and device 


times when searching by key. In VSAM RRDS retrieval the channel 


and device are busy only for the duration of the data transfer. 


During an extended search for a record in VSAM, sequential proces- 
sing can be used to read several CI's worth of records with a 


Single EXCP. 
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The formatting of an RRDS is a small fraction of the time required 
to format a BDAM data set with dummy records. The initial random 
loading of a BDAM, ESDS or RRDS data set are nearly equivalent. 
VSAM uses more CPU time than BDAM, but is better on channel time. 
It is assumed that random loading will not occur frequently. 
Backup and recovery are done sequentially which should be much 
faster with VSAM. 


Direct retrieval of a VSAM record is significantly better than BDAM 
retrieval in total elapsed time per record but uses slightly more 
CPU cycles. 


In general all operations using VSAM are better than BDAMN in 
elapsed time. VSAM operations tend to use more CPU cycles than SBPAN 
whereas BDAM uses more channel time than VSAM processing. 


5.4 ISAM VERSUS VSAM 


All ISAM applications can be mapped into VSAM KSDS applications. 
Either native VSAM support or VSAM through the ISAM Interface 
Program (IIP) may be used. Use of the IIP avoids program conversion 
(see also next section and section 5.4.3). 


Some general comments about the relative performance of VSAM and 
ISAM should be made. They are: 


= OPEN and CLOSE in VSAM are Significantly longer than in ISAM. 


- Data set creation in VSAM takes longer than ISAM depending upon 
the amount of ‘free space required, the number of buffers, and 
the blocking factor. 


- Direct VSAM operations are usually faster than the equivalent 
ISAM operation. 


~ VSAM requires more virtual storage than ISAM. 


= In sequential access, VSAM generally uses more CPU time than 
ISAM but in ordered direct, random batch and sorted batch, 
accessing VSAM generally requires less CPU time than ISAM.) 


- VSAM uses less channel time than ISAM overall. 


= In random access, the ‘path length' from the highest level 
index entry down to the record is always the same in VSAM, 
independent of the number of insertions, whereas ‘for ISAM the 
"path length’ tends to vary and become longer on the average, 
the more records have been inserted into a data set. 


= VSAM uses free space in a far better way then ISAM. KSDS 
requires much less reorganization then ISAM. 
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5.4.1 ISAM INTERFACE PROGRAM 


If a program does not require functions other than those provided 
by the original ISAM program, the IIP is an efficient means of 
using VSAM. The elapsed time and CPU time differences between IIP. 
and native VSAM is negligible. —— 


The ISAM Interface Program consists of a few modules which are 
automatically available when VSAM is used. No special generating 
is required. The only changes are as follows: . 


° The ISAM data set must be converted into a VSAM data set by 
using the Access Method Services functions: DEFINE CLUSTER (for 
defining the VSAM data set), and REPRO (to transfer the data 
from the ISAM data set to the VSAM data set). 


e The ISAM program JCL must be changed to specify the VSAM data 
set. | | | 


5.4.2 ISAM TO VSAM DATA SET CONVERSION 


Data and Index CI sizes should be set as discussed earlier. The# 
overall free space can be determined from the amount of overflow i. 
the ISAM data set. Determine the number of records that will f1it 
into all of the ISAM overflow areas of the primary extent. The 
number of records in the newly created ISAM data set plus’ the 
number of records that can be contained in the overflow areas is 
the capacity of the primary ISAM extent. The difference between 
the newly created ISAM file size and the capacity of the primary 
extent is the amount by which the ISAM £ile may grow before a 
secondary extent is allocated. Use this amount of growth (in 
records) to compute the VSAM free space as discussed earlier. 


5.4.3 ISAM PROGRAM CONVERSION USING ISAM INTERFACE | 


As described in the previous sections ISAM programs and ISAM data 
sets can be transferred easily to VSAM. | | 


The ISAM data must be transferred into a VSAM data set (with REPRO 
or a Similar user program). | 


The definition parameters of the VSAM data set are based on the 
characteristics of the ISAM data set. As ISAM differentiates 
between variable-length and fixed length records and blocked and 
unblocked records, these characteristics must be taken into account 
when defining the VSAM data set. 


The following figure shows the definition differences for fixed 


blocked and fixed-unblocked records (the characters A, B, C repre- 
sent the key of the records): . 


The ISAM definitions are for DOS/VS, the OS/VS DCB parameters are 
Similar. | | 7 | | 
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ISAM 


Access ISAM 
Method blocked records unblocked records 
DTFIS RECFM=FIXBLE, * DTFIS RECFM=FIXKUNB, 
KEYLOC=x, * KEYLEN=y, * 
KEYLEN=y, * RECSIZE=a, 
RECSIZE=25) .25.8 6% ee a or ee ie ea a 
I A_M 


uy Ue} Ue] 


DEFINE CLUSTER .... = 
KEYSCy,x-1) = KEYSCy,90) = 
RECORDSIZE (2,2) - RECORDSIZE (aty,2ty)- 


Cr cS i, Si i i a a 2 2 a 2 J 


DEFINE CLUSTER 


Figure 36. VSAM definition for fixed-length ISAM records 


Variable-length records: 


ISAM: KEYLEN=y,KEYLOC=x, * NVSAM: DEFINE CLUSTER .... = 
RECSIZE=2, 7 KEYS Cy,x-4) = 
ee eee RECORDSIZE Cavg,2-4) - 


*- © @ @ © © ® &© e® 


After copying the ISAM data into the VSAM data set, the ISAM 
program JCL must be changed to specify the VSAM data set instead of 
the ISAM data set. 


The ISAM program itself need not to be changed (as long as standard 
operations are performed). 
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When VSAM recognizes that ISAM macros are executed for a VSAM data. 


set, the ISAM Interface Routines are called automatically (without 


any specification of the user) to translate the requests and also. 


the return codes supplied by VSAM into ISAM return codes. 


It is not suggested to convert an ISAM program into a VSAM program 
as the Interface routines are very fast and use only about 11K of 
pageable storage. 


The ISAM interface support is also provided in the High Level 
Languages which use ISAM. | 


5.5 HIGH LEVEL LANGUAGE VSAM SUPPORT 


COBOL/VS, PL/I, and RPGII (DOS/VS only) provide native VSAM 
support. They provide Sequential and Random accessing capabilities. 


For further discussions see the appropriate COBOL/VS, PL/I, or. 


RPGII manuals. 
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6.0 VSAM INSTALLATION AND USAGE OF VSAM CATALOGS WITH IPL 


6.1 DOS/VS 


6.1.1 VSAM RELATED PARAMETERS IN THE SUPERVISOR (DOS/VS) 


FOPT VSAM=YES, / 
GETVIS=YES, / 
RELLDR=YES, / 

ALLOC BG=nk,...,F1=n1K n= 170K->470k( depending 
on services used) for 
partitions where Access 
Method Services is 
supposed to run. 

Or user program size © 
plus an amount equiva- 
lent to that of the 
working set indicated 
in section 9.2.1 on 
page 228. 
VSTAB r 

VSIZE=old VSIZE + nkK, / n > 350 

SVA=Cold SVA-sizge + nK,...), 7 

BUFSIZE=old value + m m > 4O/partition 

ITOTAB ‘ 

NRES=nr, / nz < 256 (number of VSAM 
Resource Usage records). 
ASSGN SYSCAT,X'cuu' Standard assignment 


for master catalog. 


6.1.2 HOW TO USE A USER CATALOG AS MASTER CATALOG (DOS/VS) 


If the standard assignment of the the master catalog has to be 
changed, it has to be specified between the '"SET' and the '‘'DPD' 
commands in the form : | 


CAT UNIT=X'cuu' 
This is the ONLY point where a master catalog can be reassigned. 


An ASSGN SYSCAT ais an IPL command. It is NOT a valid Job Control 
(JCLJ nor an Attention Routine CATTN). 


614-3 LOAD A NEW SDL/SVA (DOS/VS) 


After IPL, a new SDL/SVA has to be loaded (using ‘for instance tha 
procedure 'VSAMSVA'). This has to be done just once and remains 
valid until the VSIZE changes or the "WARM COPY of SVA‘' is reject- 
ed. See SYSGEN manual. 
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6.2 VS2 MVS 
6.2.1 HOW TO INSTALL VSAM IN VS2 MVS 
As the prime system catalog is a VSAM master catalog, VSAM support 


is always included in the system. 


The usual way to generate a MVS system is by using another MVS 
system as generating system. 


To create a master catalog for the new system, there are two 
possibilities: | 


1. Use the SYSGEN DATASET macro alone to create the master catalog. 
If the new master catalog is to be recoverable this version 
cannot be used. If this version is used and a master password 
is to be assigned to the master catalog (strongly recommended ) 
this master password must be added with an ALTER command (see 
example on page 121). 

2. Use the DEFINE MASTERCATALOG command and the DATASET macro. 

This version allows specification of all attributes valid for 


the DEFINE MASTERCATALOG command, which includes the attribute 
RECOVERABLE and the specification of passwords. 


Create the master catalog with the DATASET macro alone: 
Specify the following: 
DATASET VSCATLG, VOL=(SYSRES, 3330) ,SPACE=(CYL,(10,5)), x 
NAME=SYS1.MASTERCT 
Note: The master catalog need not be on the systems residence 
device. The resulting catalog is nonrecoverable. 


This DATASET macro results in 3 major functions: 


es DEFINE MASTERCATALOG (is treated as a DEFINE USERCATALOG in the 
generating system). | | | 


o After defining the catalog, an EXPORT DISCONNECT command is 
issued to detach the catalog from the generating system. 


° A member with the name SYSCATLG is created in SYS1.NUCLEUS 


(this is the standard member pointing to the master catalog, 
see also the next section). | 
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Create the master catalogq with pre-allocation and DATASET macro: 
Specify the following: 


DEFINE MASTERCATALOG (NAMECSYS1.MASTERCT) - 
FILE (CATVOL) = 
RECOVERABLE es 
VOLUME (SYSRES) 7 
CYL €10 5) = 
MASTERPW (MASTPROT) ) 


After executing this command (which is treated 1i1ke a DEFINE 
USERCATALOG command) an EXPORT DISCONNECT command must be issued to 
prevent the usage by the generating system. 


In the subsequent SYSGEN for the new system, the DATASET macro must 
not specify a SPACE value as follows: 


DATASET VSCATLG,VOL=(SYSRES, 3330), * 
NAMNE=SYS1.MASTERCT 


The DATASET macro creates amember with the name SYSCATLG in 
SYS1.NUCLEUS (this is the standard member pointing to the master 
catalog, see also the next section. 


6.2.2 HOW TO USE A USER CATALOG AS MASTER CATALOG (MVS) 


A member of SYS1.NUCLEUS must be defined to point to the alternate 
catalog (the user catalog to be used as master catalog). | This 
member consists of a 80 byte record as follows: 


Columns Contents 


1 to 6 Volume serial of volume containing the alternate catalog 
7 unused 
8 Device type (see following chart) 
9 to 10 unused 
11 to 54 Data set name of the alternate catalog left-justified 
and padded with blanks 
55 to 80 unused 


The device type codes Cused in column 8) and JCL block sizes are as 
follows: 


Device Code (Chex) Card Punch BLKSIZE Cin JCL) 
2305-1 : 06 12-6-9 14136 
2305-2 07 12-7-9 14660 
2314 08 12-8-9 7294 
3330 09 12-1-8-9 13030 
3330 Mod.11 OD 12-5-8-9 13030 
334073344 OA | 12-2-8-9 8368 
3350 OB 12-3-8-9 19069 
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The following job can be used to place the member in SYS1.NUCLEUS: 


//ADD JOB 

S/5TEP EXEC PGM=IEBGENER 

//35XSIN DDB DUMMY 

4/S3SYSUTZ DD DSN=SYS1.NUCLEUS(xXxXkKx),DISP=(MOD,KEEP),UNIT=univ. 


// DCB=(BLKSIZE=***X),VOL=SER=volser 
//SYSPRINT DD SYSOUT=A 7 

4S/S5SYSUT1 DD *. 

data card 


XXKK = name of the new member with the alternate catalog pointer 
= see BLKSIZE in device type code table on previous page 


Note: Do not use ITEBUPDTE to add the member because this alters the 
blocksize of SYS1.NUCLEUS and makes further changes impossible. 


If it is necessary to change the member, use IEHPROGM to scratch 
the member and then add it again. | 7 


To use the new catalog after the next IPL (cold start) the pointer 
in IEAVNP11 (Cin the NUCLEUS) pointing to SYSCATLG (SYSCATLG is the 
standard member containing the pointer to the VSAM master catalog) 
must be changed to point to the new member (see the following 
example). 


To change the pointer in IEAVNP11 the following job can be used: 


4/ZAP JOB 
S/S3STEP EXEC PGM=AMASPZAP 
S/SYSLIB DD DSN=SYS1.NUCLEUS,DISP=OLD 
Z/SYSPRINT DD SYSOUT=A 
S/SYSIN. DD * 

NAME IEAVNP11 IEAVNP11 

VER 1905 EZE8E2C3 C1iE3D3C7 


REP 1905 new member name 
sk 


Note: Before applying this change, use the AMASPZAP service aid 
program to dump CSECT IEAVNP11. Then use the dump to determine the 
exact location of the data to be altered. | 


The new catalog is used after the next IPL (cold start). 
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6.3 VS1_ AND VS2 SVS 


6.3.1 HOW TO INSTALL VSAM IN VS1 AND VS2 SVS 


VSAM is included in the system with the System Generation by 
default. 


To use VSAM a VSAM Master catalog must be created using the VSAM 
utility Access Method Services (see example in section 7.3 on page 
100). 


This DEFINE MASTERCATALOG places a pointer into the OS/VS system 
catalog with the name AMASTCAT Cindependent of the specified master 
catalog name). 


After having a VSAM master catalog defined, other VSAM data s¢t3 
and7vor user catalogs may be defined. 


6.3.2 HOW TO USE A USER CATALOG AS MASTER CATALOG(SVS/VS1) 


As the format of a VSAM user catalog and the VSAM master catalog is 
identical, any VSAM user catalog can be used as VSAM master cata- 
log. | | 


This is very important if the VSAM master catalog cannot be 
accessed due to any reason. So a user catalog can be used as a 
master catalog and the damaged master catalog can then be connected 
to the new master catalog as a user catalog to be restored. 


To use a user catalog as the VSAM master catalog, the pointer in 
the OS/VS System catalog must be changed with the following Job: 


//CHGCAT #£.JOB 


//STEP 1 EXEC PGM=IEHPROGM 

//SYSPRINT DD SYSOUT=A 

//DD1 DD UNIT=disk,VOL=SER=mcatvolser,DISP=OLD 
S/DD2 DD UNIT=disk, VOL=SER=ucatvolser,DISP=OLD 
S/85YSIN DD * 


UNCATLG DSNAME=AMASTCAT 
CATLG DSNAME=AMASTCAT, VOL=3330=ucatvolser 
s* 


After executing this job, the new catalog is used as master catalog 
atter the next IPL (cold start). 
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7.9 HOW TO START USING VSAM 


After VSAM is installed in your Operating System you may begin to 
use it. 
Access Method Services commands must be used to define the VSAM 


catalog and your VSAM data sets (in MVS the VSAM master catalog 
already exists when the system is IPIL-ed). 


General comments on this chapter: 


° To show the difference between DOS/VS and OS/VS, all the 
examples are shown on the same page in two columns. 


° To be able to print two columns on normal size paper, some 
Access Method Services messages had to be abbreviated. 

° To reduce the length of the output, most blank lines have been 
deleted. 


° The DOS/VS examples were executed with DOS/VS Rel.33. 


7.1 HOW TO CODE ACCESS METHOD SERVICES COMMANDS 


The following is a short description of how to code an Access 
Method Services command . A detailed description is included in the 
appropriate Access Method Services manual. 


Commands and their parameters can be coded in free format as shown 
below: 


COMMAND sep PARM1 sep PARM2 sep PARM3 cont 


PARMY term 


where: 
sep (separator) > 1 ory more blanks, comma(,) or comments. 
cont (continuation) >: there are two different types of 
continuation: 


1.8 value, subparameter or parameter 
has to be continued. 
Plus (+) indicates the continuation 
of a value within a parameter. The 
remainder of the value has to start 
at the left margin on next line. 


2.A command has to be continued (more 
parameter to follow). 
Minus (-) indicates the continuation 
or the same command on the next 
line(s). 
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term (terminators) : right margin or absence of continuation, 


or semicolon(;) or blank line. 


comments format : sk any text *7 . A comment line placed 
between 2 command lines must have a 
continuation sign (-). 


left/right margins : the default left and right margins are 
at columns 2 and ~“72. They can be 
changed with the PARM MARGINS command. 


some rules and recommendations: 


86 


Abbreviations of commands and keyword parameters can be inter- 
mixed with full naming. 


An easy check of the continuation rules within a command verb 
is possible if the continuation sign (-) is always placed in 
the same column (see following examples). 


Note: If no continuation sign (-) is coded and more parameters 
belonging to the same command follow, the subsequent parameters 
are ignored and defaulted by VSAM up to the next command (if 
required parameters are missing, an error message is issued). 
As this may lead to unexpected definition values, it is 
suggested to issue a LISTCAT command following each DEFINE 
command. 


There are two types of parameters : positional and Keyword 
parameters. In a parameter list or sublist, positional parame- 
ters must always be specified first (positional parameters are 
required parameters. 


Example: INFILE ( dname ENV ( ... ) ) correct 
INFILE € ENV ( ... ) dname ) wrong 


Neither commands nor keyword parameters (in long or short form) 
are reserved words: therefore it is dangerous and not suggested 
to use parameters or Keywords as component names (e.g. dont use 


UPDATE as a data set name, as this is a parameter for Access 


Method Services). 


DOS/VS only : when Access Method Services is used for tape 
operations specific 'SYSnnn', is required, i.e.: 


SY¥S004 : for input tape(s) 
SYS005 : for output tape(s) 
For functions using disks, any 'SYSnnn' can be chosen. 


The default assignments are: 


SYS006 : for input disk(s) 
SYS007 : for output disk(s) © 
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7.2 EXPLANATION OF IMPORTANT DEFINE PARAMETERS 


VSAM uses catalogs as a central information point for all VSAM data 
sets and the direct-access volumes on which they are stored. You 
can define a VSAM object in a VSAM catalog only by using the Access 
Method Services DEFINE command. Additionally, you can use the 
DEFINE command to define nonVSAM objects ina VSAM catalog Cin 
DOS/VS nonVSAM objects can only be defined in a nonrecoverable 
catalog; in MVS nonVSAM objects may also be defined using the JCL 
parameter CATLG). 


When you issue the DEFINE command to catalog an object, Access 
Method Services builds one or more catalog entries to describe the 
object. 


The VSAM objects you can define are: 


e Master catalog (in MVS this command creates a user catalog) 
e User catalog 
° Data space 
° Cluster, or VSAM data set. 
There are three types of cluster data organization: 
- ESDS (Entry Sequenced Data Set) 
= KSDS (Key Sequenced Data Set) 
= RRDS (Relative Record Data Set) 
° Alternate index 
° Path : | 
e NonVSAM data set Cin DOS/VS only in nonrecoverable catalog and 


for compatibility purposes) 


In MVS systems additionally the following can be defined: 


e Alias Calso in SVS possible) 
° Generation Data Group (GDG) 
e Page space 


Many parameters may be specified for the various DEFINE commands. 
The most important ones are described in detail (others are 
described with the example): | 


¢ FILE 

¢ FREESPACE 

¢ IMBED/REPLICATE 

* KEYRANGES 

¢ NAME 

*  RECORDSIZE 

* SHAREOPTIONS 

¢ SPEED/RECOVERY 

¢  SUBALLOCATABLE/UNIQUE 
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The FILE parameter refers to the 'filename' of a DLBL statement 
(DOS/VS), or to a 'dname' of a DD statement (OS/VS). 


The FILE parameter and its associated JCL statement is always 
required, when a volume has to be mounted to change the VTOC and/or 
ene CRA on that volume (not MVS, see 'MVS Roe below). 


MVS note: FILE may be omitted and tie ecqwieed volume e dynamical- 
ly allocated (Cassuming the volume has been mounted with the correct 
attributes). 

The following commands require a FILE parameter (not MVS, see 'MVS 


note"): 


DEFINE MASTERCATALOG 


e 

° DEFINE USERCATALOG 

e DEFINE SPACE 

° DEFINE ALTERNATEINDEX/CLUSTER with the UNIQUE attribute 

° VERIFY’ | 

1 FILE is always needed for VERIFY (even for nonrecoverable 

catalog) and is not used to identify the CRA volume, but to 
identify the DD statement which names the data set to be 
opened and verified. | 7 

Most Access Method Services commands modifying recoverable 


catalog must have a FILE parameter and its pee ca” JCL statement 
(in OS/VS the JCL statement may be omitted (not suggested), if the 
requested volume is already allocated by aan other JCL statement or 
when the catalog itself resides on the volume). 


The FILE parameter is required for the following commands’ when 
uSing a recoverable catalog (not MVS, see 'MVS note'): 


ALTER 

DEFINE commands 
DELETE 

IMPORT? 
IMPORTRA® 


ee ¢@¢ 6 ¢ @ 


4 FILE is only needed in a nonMVS system if the components are 
unique and reside on different device types (FILE must be 
coded separately for the data and index components); other 
Wise FILE 18S not needed. 


7.2.2 FREESPACE 
A KSDS can be specified to reserve space to be held free when 


loading data (see also section 2.5 on page 20). 
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Tne specified amount is only held free, when sequential insertions, 
such as ‘loading' or 'mass insertion’ (see section 8.8 on page 297) 
are performed. 


Two values can be specified: FREESPACE(CI-percent CA-percent). 


e "CI-percent’ specifies the amount of Space to be held free per 
control interval (CI). 


The way VSAM treats this free space definition is: specified 
percentage times actual CI size (rounded down to a full byte). 
So VSAM does not care about record length and does not round 
the value up, if the amount of free space is less then one 
record. 


Example: 
Definition: 


Control Interval Size 
Free space 


1024 bytes 
15 % free CI space (FREESPACE (15 0) 


VSAM calculation: 


—©47024 * «15 42 = 153,6 = 153 bytes minimum free space Cexclud- 
ing control fields). 
e "CA-percent’ specifies the amount of control intervals to be 


held free per control area (CA). 


If the maximum value (100%) is specified for both Ci-percent and 
CA-percent, each control interval will contain one record and each 
control area will contain one used control interval. 


Section A.6.2 on page on 258 contains a description of FREESPACE 
considerations when issuing the IMPORT command. For a special 
definition using different FREESPACE values, see also section 8.4 
on page 199. | 


7.2.3 IMBED/REPLICATE (INDEX OPTIONS ) 


When a Key-sequenced data set is processed sequentially, the 
sequence set index level is used to indicate the order in which 
control intervals are to be accessed. To improve performance during 
sequential processing, the index sequence set can be separated from 
the rest of the index component (index set levels) and stored with 
the logical records in the data component (IMBED). When this option 
is chosen, the index records for a control area are placed on the 
first track of the control area that both index and logical records 
can be accessed without moving the disk arm (Similar to the loca- 
tion of the track index within the prime area in an ISAM data set). 
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When the index sequence. set is Se ored: within the data component 
(IMBED), sequence set records are also. replicated. That is, each. 
sequence set index record is allocated one track at the beginning 
of the control area. The index record is duplicated on the track as 
many times as it will fit. This technique significantly minimizes 
the rotational delay involved in arriving at the beginning of an. 
index record. If there is only one control area in a cylinder, 
index sequence set records will be replicated beginning with track 
0. If there are two control areas ina cylinder, initial tracks of 
the first area will contain replicated _ index» records for the first 


control area, while initial tracks of. the second area widd contain | 


nepeECeLer index records for the second. control area. 


Index set records, like index sequence set records, contain 
compressed index entries. The index entries in each level of the 
index set point to index records of the next lower index level. An 
index entry within the index set contains a pointer to an index 
record, the highest key in that index record, and control informa- 
tion. Index set levels can also be replicated (REPLICATE). When 
this option is chosen, one track is required for each index record 
in the entire index set. An index record is duplicated on its 
assigned track as many times as it will fit. i ee | 


The index set may not be replicated when the index set and the 
sequence set of the primary index are physically separate (sequence 
set stored with logical records). However, when the index set and 
the sequence set are stored together, both are replicated or 
neither is replicated. 7 : a ~ 


The following combinations are possible: 


° NOIMBED NOREPLICATE: 
All index levels are stored Sd and are not replicated. 


e NOIMBED REPLICATE: | 
All index levels are stored together, each index record occu- 
pies an own track and is repeated on this track as often as 
possible. ; a | | 


._ = IMBED NOREPLICATE: 


The index sequence set ievel is stored ak the data component. 
Each index record in the index sequence set is stored with its 
data control interval, occupies an own track, and is repeated 


on this track as often as possible. In most cases this is the 
best choice. The higher index levels are not repeated ona 
track. oo ee FG | 


° IMBED REPLICATE: | 
The index sequence set Level is whered with. the data eonesacne: 
Each index record in the index sequence set is stored with its 


data control interval. Each index sequence set record occupies 
its own track, and is repeated on this track as often as 
possible. s ° | | | : | 
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7.2.4 KEYRANGES 


KEYRANGES is a DEFINE parameter and specifies that ina KSDS 
specific key ranges are to be stored on specific volumes. 


As the user Knows (Cor should Know) which volume is to be used for a 
specific Key range, he can mount the volume he needs with a so 
called subset mount (see also section 8.10 on page 216). 


The allocation algorithms (Camount of primary and secondary space} 
and the rules for multivolume data sets are explained in the 
section 8.1.3.3 on page 188. 


When using Key ranges, data on a specific volume can be restored 
from a backup tape (with full volume restore, which may lead to a 
data set ‘'out-of-synch' condition), as usually all Keys of a Yaw 
range are stored on one volume (see following examples). 


e Example 1 (3 key ranges, 3 volumes) 


DEFINE CLUSTER ... VOLUMES (V1,V2,V3) = 
KEYRANGES (C(A,F) (G,P) (2,2)) = 
CYL (100,50) 


A-F ) G-P > 2-2 S) 
as se 8 
“once a] ue 


Primary allocation 
Secondary allocation 


*? 
to ott 


Figure 37. Keyranges (example 1). 
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e Example 2 (2 key ranges, 3 volumes) 


DEFINE CLUSTER ... VOLUMES (V1,V2,V3) 
KEYRANGES ((A,F) (G,2Z)) 
CYL (100,50) 


Primary allocation 
Secondary allocation 


J 
no 


Figure 38. Keyranges (example 2). 


e Example 3 (5 key ranges, 3 volumes) 


DEFINE CLUSTER ... VOLUMES (V1,V2,V3) | - 
KEYRANGES (CA,D) (CE,H) (I,M) (N,R) €5,2)) - 
CYL (100,50) 


P E-H Par TSM Pp 
Ss E-H ) | 
| E-H inane, Ss N-R Pp 


P = Primary allocation 
= Secondary allocation 


Figure 39. Keyranges (example 3). 


92 VSAM PRIMER and REFERENCE © 


° Example 4 (4 Keyranges, 2 volumes (twice specified) ) 


DEFINE CLUSTER ... VOLUMES (V1,V2,V1,V2) = 
KEYRANGES ((CA,D) (E,H) C(I,M) (N,Z))- 
CYL (100,50) 


iL-M P N-Z P 
L=M S E~H S 
la Seen ee “e 
P = Primary allocation 
S = Secondary allocation 
Figure 40. Keyranges (example 4). 
7.2-5 NAME 
The name specified for a VSAM data set may contain 1 - 44 alphanu- 


meric characters, national characters (d, # and $) and two special 
characters (Chyphen and 12-0 overpunch). 


Names containing more than eight characters must be segmented by 
periods; one to eight characters may be specified between periods. 


The first character of a name or name segment must be either an 
alphabetic or national character. 


With multiple catalogs you should take care that a data set name in 
one catalog is not duplicated in another catalog. 


It is possible to have the same data set name in more than one 
catalog. 


Access Method Services prevents you from cataloging two objects 
With the same name in the same catalog, and from altering the name 
of an object that its new name duplicates the name of another 
object in the same catalog. 7 


Duplication is not checked or prevented when a user catalog is 
imported into a system (see IMPORT CONNECT command on page 166). 
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No check is made to determine whether the imported catalog contains 
a name that another catalog already in the System contains. For 
cluster naming conventions see also section 2.9.2 on page 43. 


In MVS systems, the data set name can also be used to identify the 


catalog where the data set is cataloged. A name segmented with 
periods is called a qualified name. The first qualifier (the part 


of the name up to the first period) is used to find the user 
catalog if no STEPCAT or JOBCAT catalog is specified (the Access 
Method Services manual contains a section ‘Order of catalog use' 
for each command, where the catalog search sequence is described). 


Note (MVS only): As the data set name (qualified name) is used for 
catalog allocation a qualified name and an unqualified name cannot 
exist in the same catalog if the first qualifier of the qualified 
name is the same as the unqualified name. 


The example in section 4.4 on page 60 does not work in a MVS system 
and is rejected with a message ‘DUPLICATE DATA SET NAME’, because 
the cluster name is CITY and the data component name is ‘'CITY.D’ 
which is then a violation of the restriction described above. 


To prevent these problems, it is suggested always to use qualified 
names in an MVS system and always use the same first qualifier in 
one catalog. — 


This first qualifier should be identical with the ALIAS or the 
catalog name defined for the user catalog. 


7.2.6 RECORDSIZE 


As described on page 8 there is no Special parameter to define that 
fixed-length records or variable-length records are to be used. 


The RECORDSIZE parameter indicates, however, bie fixed-length 
records are to be used or not. 


The format of RECORDSIZE is: 
RECORDSIZE Cavg.length max.length) 


If fixed-length records with a length of 80 bytes are to be used, 
the definition would be RECORDSIZE (80 80). 


The definition of RECORDSIZE (60 80) would, however, also enable 
the user to use fixed-length records with 80 bytes, because the 
‘avg.length’ parameter is only used by VSAM to calculate tke 
minimum control interval size for the data component (or to chee" 
the size the user has defined). 


the "avg.length' parameter is also checked when an RRDS is being 
defined (in this case ‘avg. length" and ‘max. length" must have the 


same value, since fixed-length records are required for RRDS). 
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The ‘max.length' parameter is a limiting size for VSAM. Records 
With a larger size will force an error message, but if RECORDSIZE 
(100 100) has been specified and only records with a length of 80 
bytes are used, neither error messages are written nor is space 
wasted on disk Cexcept for an RRDS data set whose slots are prefor- 
matted depending on the 'max.length' parameter), as VSAM checks the 
actual length of the record and stores this information in the RDF 
(Record Definition Field). 


7.2.7 SHAREOPTIONS AND DATA SET SHARING 


A VSAM data set can be accessed concurrently by two or more 
subtasks within the same partition and two or more job steps 
(partitions) Cin OS/VS DISP=SHR must be specified for the VSAM data 
set by each job step). Both types of sharing can be used for a 
VSAM data set at the same time. The type of data set sharing 
permitted for two or more partitions is controlled by using the 
SHAREOPTIONS parameter of the DEFINE command when the VSAM data set 
is defined. 


The format of the SHAREOPTIONS command is as follows: 


SHAREOPTIONS (cross-region [cross-system] ) 


7.2.7.1 CROSS-PARTITION/REGION SHARING 


The following types of options are supported: 


* SHAREOPTIONS (1): 


The data set can be opened by one user for output processing 
(to update or add records) or the data set can be opened by 
multiple users ‘for read operations only. Full read and write 
integrity is provided by this option. 


° SHAREOPTIONS (2): 


The data set can be opened by one user for updating or record 
addition (Coutput operations) and by multiple users for 
read-only processing. Since only one user can perform write 
operations, write integrity is provided by this option. Howev- 
er, read integrity must be provided by each user since users 
can read a record that is in the process of being updated. 


° SHAREOPTIONS (3): 
The data set can be opened by any number of users for both read 


and write operations. Data set integrity must be maintained by 
the user. No integrity (read or write) is provided by VSAM. 
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- SHAREOPTIONS (4): 


The data set can be opened by any number of users for both read 
and write operations. For direct processing operations, VSAM 
provides a new buffer for each request. Control interval | 
splitting should be avoided when this option is used (to 
prevent a possible CA split). | 


In DOS/VS the 'trackhold £acility' is used to insure the 
appropriate integrity. 


In OS/VS the EN2 and DE@ macros must be issued by users to 
maintain data integrity. 


VSAM will not allow a control area split (and no CI split of 
the ‘high key CI' for SHAREOPTION 4 sharing of a Key-sequenced 
data set. VSAM indicates 'NO SPACE AVAILABLE' if an attempt is 
made to add or change the size of a record anda control area 
split is required to perform the operation. 


OS/VS Notes: Data set sharing by subtasks within the same 
partition can be accomplished using one DD statement for the 
VSAM data set or multiple DD statements. When a single ODD 
statement is used, multiple subtaskKs in the same partition can 
perform read and update operations on the VSAM data set. VSAM 
uses the exclusive control facility to maintain integrity 
during update operations. The SHR disposition parameter need 
not be specified in order to share a VSAM data set when one DD 
statement is used. However, if DISP=SHR is specified when one 
DD statement is used, both subtask sharing and cross-partition 
sharing (as described above) can be used concurrently. 


When multiple DD statements are used, multiple subtasks within 
a partition can share a VSAM data set using the same options as 
are supported for cross-partition sharing. The DISP=SHR parame- 
ter must be specified on the DD statements. 


Note the following restriction: When DISP=SHR and SHAREOPTION 4 
is specified for cross- partition or cross-system sharing, 
VSAM provides a new buffer for each direct processing request, 
and users should be issuing EN@/DE@2 or RESERVE/RELEASE macros 
to ensure data set integrity. 


7.2.7.2 CROSS-SYSTEM SHARING COS/VS ONLY) 


The following options are supported in OS/VS (they may: be epeceried 
in DOS/VS but are meaningless): 


SHAREOPTIONS (C(x 3): 


The data set can be opened by any number of users for both read 
and write operations. Data set integrity is a user responsibil- 
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ity as VSAM does not provide any. 


° SHAREOPTIONS (x 4): 


The data set can be opened by any number of users for both read 
and write operations. VSAM provides a new buffer for each 
direct processing request and RESERVE and RELEASE macros must 
be issued by users to maintain data set integrity. All job 
steps that are accessing a VSAM data set concurrently must 
specify DISP=SHR if data set integrity is to be maintained. 
Control interval splitting should be avoided. 


Note the following OS/VS restriction: When DISP=SHR and SHAR- 
EOPTION 4 is specified for cross- partition or cross-system 
sharing, VSAM provides a new buffer for each direct processing 
request, and users should be issuing EN@/DEQ or RESERVE/RELEASE 
macros to ensure data set integrity. 


VSAM will not allow a control area split (and no CI split of 
the ‘high Key CI' for SHAREOPTION 4 sharing of a Key-sequenced 
data set. VSAM indicates 'NO SPACE AVAILABLE' if an attempt is 
made to add or change the size of a record anda control area 
split is required to perform the operation. 


7.2.8 SPEED/RECOVERY (LOADING OPTIONS) 


When a VSAM data set is loaded, VSAM does or does not preformat 
control areas, depending on the attribute specified when the data 
set is defined, RECOVERY or SPEED, respectively. 


When RECOVERY (the default) is specified, during loading VSAM 
preformats each control area immediately before loading any records 
into it. Preformatting for a key-sequenced data set consists of 
putting the appropriate control information in each control inter- 
val and an end-of-file indication in the first control interval in 
the next control area after the control area just preformatted. 
All zeros in the control interval definition field indicates end of 
file or end of Key range for a key-sequenced data set. | 


For an entry-sequenced or relative record data set, control infor- 
mation and an end-of-file indication are placed in each control 
interval of the control area during preformatting. 7 | 


The RECOVERY option (not suggested) ensures that if an error 
occurs, that prevents further processing while a control area is 
being loaded, the previously loaded control areas are not lost. 
Loading can resume from the first or only end-of-file indicator. 
Preformatting in RECOVERY mode is always done when records are 
added to an existing VSAM data set (even if SPEED was specified). 


When SPEED is specified (suggested), records are loaded (i.e. 
between first OPEN and CLOSE) without preformatting each control 
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area before loading and the | end-of-file indicator is not written 


until the data set is closed. When this option is chosen, loading 
proceeds more rapidly, but if an error that prevents further 
processing occurs, all the records loaded up to that point may be 
lost and loading would have to resume at the beginning of the data 
set. | : | gt : 


The following should be considered when using RECOVERY: 


° Up to now when an empty data set is loaded, the ‘high used RBA' 
(see page 156) is only updated if the data set has been closed 
(by the user) after at least one record written into it, or if 
a second extent has to be allocated. | 


. Since VERIFY does not work for a data set with a ‘high used RBA 
te = 0', which usually indicates an empty data set, loading could 
not be resumed, even when RECOVERY is specified. 


e Tf the user-written load program had issued a CLOSE while 
loading the data set (while REPRO does not), VERIFY may be used 
after a system malfunction to adjust the ‘high used RBA’ and 
the loading may be resumed (the user has to check which record 
was entered last and he has to change the load program to 
resume loading with the next record). 


° It ais suggested to always specify SPEED which is not the 
default. 


7.2.9 SUBALLOCATION/UNIQUE 


As described in section 2.9 on page 40 VSAM uses two different 
types of data spaces/data sets in terms of allocation. 


The SUBALLOCATION parameter specifies that a data set shares a 
predefined VSAM data space with other VSAM data sets. | 


VSAM does all the space management and no JCL specification for the 
location of the data set must be given (DOS/VS). 


SUBALLOCATION is the way of allocation VSAM is designed for. 


For DOS/VS suballocated data sets offer a similar DASD management 
as DADSM provides for OS/VS. 7 7 : 


For OS/VS the advantage (if using suballocated data sets) is that 
the 16 extent restriction per volume does not apply and therefore 
the disk space can be used more flexibly. 


The UNIQUE parameter requires a separate allocation for the data 
set. | | : | | 


DOS/VS user must specify the number of tracks and the offset in the 
DLBL EXTENT statement when a UNIQUE data set is to he defined. © 
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One FI-DSCB (Label) (or two for a KSDS) are written into the vToc 
for the UNIQUE data set. 


The name in the F1 DSCB is the data component name (and for a KSDS 
the index component name). 


The ‘cluster name specified in the DEFINE command is not used in the 
VTOC. Therefore it is recommended to specify also a name for the 
data component (and in case of a KSDS, also a name for the index 
component), since otherwise VSAM would generate its own 44-Byte 
name which is meaningless to the user when listing the VTOC or the 
catalog (LISTCAT). 


UNIQUE data sets should he restricted for special applications. 


DOS/VS users should also read the restrictions for UNIQUE data sets 
when using recoverable catalogs (section A.4 starting on page 250}. 
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7.3 DEFINE MASTERCATALOG 


As described in chapter 3.0 starting on page 47, the first step of 
creating VSAM objects, is to define the VSAM master catalog (see 
also the appropriate sections in chapter 6.0 starting on page 79). 

In MVS systems, a VSAM master catalog cannot be defined for the 
active system; each DEFINE MASTERCATALOG is treated as a DEFINE 
USERCATALOG. | | 


Since any user catalog, however, can be used as master catalog (sea 
the appropriate section in chapter 6.0), this discussion is also 
valid for MVS systems. | 


1. Since it is advisable that the master catalog (MCAT) should 
contain only the UCAT'’s pointers (plus CVOL pointers and ALIAS 
entries for MVS systems) it can be defined with CYL (1 1), 1£ it 
is a nonrecoverable catalog (see also section A.4 on page 250)... 

2. As described in section A.4.3.1 on page 252 the master catalog 
need not be RECOVERABLE. | 

3. Even when the original space definition was large enough to hold 
all future entries, a secondary allocation value should ke 
specified, as it is avery time consuming process to recover 
from a ‘catalog full" condition. 

4. The master catalog should be made password protected in order to 
prevent its accidental (or unauthorized) deletion or update. If 
the master catalog is password protected, severe delete func- 
tions, such as DELETE USERCATLOG FORCE (OS/VS only) or ALTER. 
REMOVEVOLUMES (a special OS/VS ‘function to delete all VSAM 
information on a disk, see example on page 181) are prevented as 
long as the master password is not specified. | 


DOS/VS example (input): OS/VS example (input): 
7/ JOB DEFINE MASTER CATALOG //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL IJSYSCT, 'PRIMER.MCAT' ,99/365,VSAM 77PRIMOOL2 EXEC PGM=IDCAMS 
7/7 EXTENT SYSCAT,DOS30Z>, 4560538 _  AANOLL DD VOL=SER=HTVSMC ,DISP=OLD ,UNIT=3330 
/7 EXEC IDCAMS, SIZE=AUTO /7SYSPRINT DD SYSOUT=A 
| //SNSIN DD * 
DEF MCAT ( - DEF MCAT ( - 
NAME( PRIMER .MCAT) = NAME (PRIMER.MCAT) = = 
FILE (IJSYSCT) . FILE (VOL1) = 
VOLUME (D0$30Z) - VOL (WTVSMC) 2 
CYL (1:1) - cYL (1:1) - 
MASTERPW (MCATMRPH) = - MASTERPW (MCATMRPH) = - 
) | ) 
/& /* 
DOS/VS example (Coutput): OS/VS example (Coutput): 


IDCO510I CAT. ALLOC. STAT. FOR VOLUME DOS30Z IS 0 IDCO510I CAT. ALLOC. STAT. FOR VOLUME WTVSMC IS 0 
IDCOOO1T FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 6 IDCOQO02T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
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Notes: 


The NAME parameter specifies the name of the master catalog. 


The FILE parameter is required (not for MVS, see also section 
7.2.1 on page 88). 


The VOL or VOLUME parameter specifies the volume the catalog is 
to be allocated. | 


The CYL or CYLINDERS parameter specifies the amount of primary 
and secondary space to be allocated for the VSAM data space, 
which is created with this command (see also section 2.11 on 
page 45, 189). 


Since no DATA and INDEX parameters are specified the master 
catalog occupies the whole data space (see also begin of next 
section DEFINE USERCATALOG). 


The MASTERPW parameter specifies the master password (MCATMR FW; 
for the master catalog (see also section 3.3 on page 52). 


DOS/VS notes: 


The ‘dname* must be IJSYSCT in both the DLBL and the FILE 
statements. 


The EXTENT must begin on a cylinder boundary. Since the 
primary allocation is one cylinder and the catalog is not 
RECOVERABLE, an EXTENT specification of two cylinders (38 
tracks on 3330) leaves one cylinder for catalog extension or 
suballocatable space since the master catalog will contain only 
user catalog pointers. | 


No ASSGN is necessary since it has been specified either in the 
Supervisor or at IPL-time. 


The DLBL/EXTENT information will be stored in the STDLABEL 
area, so they have been omitted in the following examples. 


The line ' //EXEC IDCAMS SIZE=AUTO ' is followed by one or more 
Access Method Services commands as printed in the output. 


A '/*' signals end of input to Access Method Services. 


OS/VS notes: 


The line ‘* //SYSIN DD * ' is £ollowed by one or more Access 
Method Services commands as printed in the output. | 


A '/** or 'vsv' (next step) signals end of input. 
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7.4 DEFINE USERCATALOG 


As discussed in chapter 3.0. starting on page 47 user catalogs 
should be used to ease transportation of VSAM data sets and catalog 
recovery. ‘ | 


DEFINE USERCATALOG creates a suballocatable data space on a volume 


not owned by any other VSAM catalog. If the catalog entries are 
changed often by deleting or adding of VSAM objects, it might be 
advisable to reserve for the catalog its own data space to prevent 
secondary allocation being built for form the catalogs prime 
allocation. . 


To do so, do not specify DATA or INDEX parameters in the DEFINE 
USERCATALOG command. Thus the whole space specified with the SPACE 
parameter will be assigned to the user catalog (the UNIQUE attri- 
bute is not allowed in this command). | : 


In DOS/VS the size-definition in the EXTENT parameter determines, 
only if the catalog resides in this space. 


To define the user catalog the following assumptions were made: 


e The user catalog occupies its own data space (therefore neither 
DATA nor INDEX parameters were specified). 


@ The update password allows definitions of VSAM objects without 
knowing the master password. The master password is required 
for all other functions (like deleting entries, alter passwor's 
etc.) but the read-only ones. It is also required for the 
function LISTCAT ALL (when the passwords are to be listed). 


° The user catalog is recoverable, therefore a CRA (catalog 
recovery area) with a size of one cylinder is allocated in 
addition to the specified catalog space, either by OS-DADSM or 
by DOS/VS using space specified in the EXTENT statement. 


° In our example, the UCAT has to be large enough to contain 


(long range planning): 


~ 15 KSDS siuetaxs 

- A ESDS clusters 

_ 2 RRDS clusters 

- 5 Alternate indexes 
oe 5 Paths 


= 2 Volumes owned by the catalog. 
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The number of tracks required can be calculated using the worksheet 
shown in the section 'Estimating the Catalog's Space Requirements' 
of the Access Method Services manual (see page 2). 


Based upon the previous assumptions, the worksheet result is a 
minimum of 99 entries or 15 tracks for the primary allocation. 
This value was rounded up in the example to 2 cylinders. 


DOS/VS example (input): OS/VS example Cinput): 
// JOB DEFINE USER CATALOG //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// OLBL IJSYSUC,''PRIMER.UCATL', VSAM //7PRIMO022 EXEC PGM=IDCAMS 
// EXTENT SYSQ10,NTVSAM> » 119557 //NOLI DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR //SYSPRINT DD SYSOUT=A 
7/7 EXEC IDCAMS,SIZE=AUTO //SYSIN DD * 
DEF UCAT ( - DEF UCAT ( - 
NAME (PRIMER.UCAT1) - NAME (PRIMER.UCAT1) - 
FILE (IJSYSUC) ~ FILE (VOLL) ~ 
‘VOL (HTVSAM) = VOL (HTVSAM) - 
CYL (2 1) - CYL (3 1) - 
MASTERPHW (UCATMRPW) - MASTERPW (UCATMRPH) - 
UPDATEPW (UCATUPDT) - UPDATEPW (UCATUPDT) - 
RECOVERABLE - RECOVERABLE - 
) -) 
7% /* 
DOS/VS example Coutput): OS/VS example Coutput): 


IDCOS510I CAT. ALLOC. STAT. FOR VOLUME WTVSAM IS 0 IDCO510I CAT. ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCOQO1IT FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


bree: | 


LISTCAT output of this object is shown later in section 7.9.2 


Notes: 
6 The FILE parameter is required (not for MVS, see also section 
7.2.1 on page 88), as the VTOC of the volume to contain the 


catalog has to be modified (build F1-DSCB (Label), set VSAM 
"ounership-bit' ON). | 


The notes are continued on the next page. 
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DOS/VS_ notes: 
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The 'dname' may be any name, but choosing IJSYSUC allows the 
DLBL/EXTENT to be cataloged in the PARSTD area and makes this 
UCAT default to the user catalog. 


The EXTENT of 3 cylinders contains 


- The UCAT primary allocation (2 cylinder) 
=: The CRA (1 cylinder) 


In case of a catalog overflow, any free cylinder in the subal- 
locatable space(s) of this catalog (not yet defined) will be 
used for secondary allocations. 


OS/VS_ notes: 


The value ‘CYL (3 1)' specifies, that 2 cylinders are to be 
used for the catalog (no DATA and INDEX parameter specified 
(see description for DEFINE MASTERCATALOG)) and 1 cylinder is 
to be used as CRA (catalog recovery area), since the RECOVERA- 
BLE parameter is specified. | | 


Up to a total of 15 extents can be allocated if necessary (in 
extents of 1 cylinder). 
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DEFINE SPACE 


This command creates a suballocatable data space with a primary 
allocation of 100 cylinders. 


DOS/VS example Cinput): OS/VS example (Cinput): 
// JOB DEFINE SPACE //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
/7 OLBL SPACE,,,VSAM /7PRIMO032 EXEC PGM=IDCAMS 
//7 EXTENT SYSO10,HKTVSAM; » » 76,1900 //SPACE DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
// ASSGN SYSO010,DISK, VOL=WTVSAM, SHR //SYSPRINT DD SYSOUT=A 
/7 EXEC IDCAMS, SIZE=AUTO — Z7SYSIN DD * 
DEF SPACE ( - DEF SPACE ¢ - 
FILE (SPACE) - FILE (SPACE) - 
VOL (WTVSAM) - VOL (WTVSAM) | - 
CYL (100) - CYL (100;,2) - 
) - ) - 
CAT (PRIMER.UCATI1/UCATUPDT ) CAT (PRIMER.UCAT1/UCATUPDT ) 
7 & /* 
DOS/VS example (output): OS/VS example (Coutput): 


IDCO511I SPACE ALLOC.STAT. FOR VOLUME WTVSAM IS 0 IDCO511I SPACE ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IDCOOOLI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION CONPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


LISTCAT output of this object is shown later in section 7.9.2 | 


Notes: 


The FILE parameter is required (not for MVS, also see section 
7.2.1 on page 88), as the VTOC of the volume to contain the 
data space has to be modified Cbuild F1-DSCB (Label)), and a 
copy of the data space entry has to be written into the CRA. 


The CAT parameter must be coded since the UCAT is password 
protected. 


DOS/VS notes: 


@ 


Defining a SPACE (as well as any UNIQUE cluster) requires an 
EXTENT specification where the object is to be placed. 


The secondary allocation for SPACE is not used in DOS/VS. Such 
a specification would , if indicated, be recorded in the 
catalog for OS/VS compatibility only. 

The FILE parameter also indicates to the DOS/VS system routines 


the amount fo space controlled by VSAM. 
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7.6 KSDS (KEY-SEQUENCED DATA SET) 


7.6.1 DEFINE KSDS 


DOS/VS example Cinput): —  OS/VS example Cinput): | 
// JOB DEFINE KSDS IN VSAM SPACE — —— /7PRIMER =: JOB: WTSC, IBM, MSGLEVEL=1 
// DLBL KSDS, 'CUSTOMER.K', » VSAM 2 /PRIMOOG2 EXEC PGM=IDCAMS | 7 
//7 EXTENT SYS010,WTVSAM _ //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
77 ASSGN SYS010,DISK,VOL=WTVSAM,SHR _ 77SYSPRINT DD SYSOUT=A | | 
// EXEC IDCAMS,SIZE=AUTO : _. -Z/7KSDS ~—s«dDD:-« VOL=SER=WTVSAM,DISP=OLD , UNIT=3330 
DEF CLUSTER - //SYSIN DD * — es _ : 
( - DEF. CLUSTER” ee 
NAME (CUSTOMER .K) -— | | — 2 
FILE (KSDS) - NAME (CUSTOMER .K) - 
VOL (WTVSAM) - 4 | ss PILE (KSDS) sie 
CYL (5 2). - ; _ VOL (WTVSAM) - 
INDEXED - 3 YL OB 2D oe 
IMBD = - INDEXED - 
) r | -IMBD 2 ——sis 
DATA ( - : ae Pe a 4 ae 
NAME (CUSTOMER.K.D) =. DATA 
RECORDSIZE (200 200) - — a NAME (CUSTOMER.K.D)—- 
KEYS (50) - i | RECORDSIZE (200 200) - 
FSPC (20 10) oe we KEYS (5 0) - 
CISZ (1024) oe ae  -Fspe (2010) = i= 
} | oe | 3 — CISZ (1024) - 
INDEX ( oe | oY . © a 
NAME (CUSTOMER.K.I) = - . INDEX (| ey oe 
CISZ (2048) - ig 8. - NAME (CUSTOMER.K.I) = - 
) | - — CISZ (2048) aie 
CAT (PRIMER .UCAT1/UCATUPDT ) : ») a sr ae 
78 | — CAT (PRIMER .UCATL/UCATUPDT ) 
DOS/VS example Coutput): © | OS/VS_ example (output): 


IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS Oo IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM Is 0 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 

IDCOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO0O01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO0Q02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 rpC0002TI IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


see notes on next page. — 
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Notes: 


° INDEXED specifies that the cluster is a KSDS. 


e The sequence set will be IMBEDded within the data i.e. every 
sequence set CI will be replicated to fill the first logical 
track of the corresponding CA. NOREPLICATE is assumed per 
default for the index set. 


e As DATA- and INDEX-names are specified, VSAM does not have to 
generate names itself. 


e According to the calculation made in section 8.3 on page 197, 
the minimum INDEX-CISZ is 2 K. If this parameter specification 
is too small, a higher value will be used by VSAM without the 
user being notified by any Kind of message. It ais therefore 
recommended to look carefully in the LISTCAT output for any 
difference between what has been specified and what VSAM 
stated. 


DOS/VS notes: 


° IJSYSUC is stored in the STDLABEL area. 


e The VSAM data set name in the DLBL statement is optional for 


DEFINE. 

e The defined KSDS is suballocated (default), i.e. it occupies a 
certain amount of space anywhere in a pre-defined VSAM space on 
the volume specified in the EXTENT ‘volid’. Therefore only one 


set of DLBL and EXTENT (short form) is required. For a UNIQUE 
KSDS cluster two pairs of DLBL/EXTENT (£ull form) would be 
required, one for the DATA part of the cluster, the other for 


the INDEX. 

° Since the user catalog is recoverable, the FILE parameter is 
needed to address the CRA through DLBL/EXTENT and ASSGN state- 
ments. , 
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7.6.2 REPRO (LOAD A KSDS) 


DOS/VS example Cinput): | OS/VS example Cinput): 
77 JOB LOAD KSDS FROM DISK-SAM  //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
77 DLBL SQDSK, 'KSDS.LARGE.DATA' //PRIMOOS2 EXEC PGM=IDCAMS 
/7 EXTENT SYS000555,7562,57 //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
// ASSGN SYS000 ,DISK, VOL=D0S30Z,SHR //SQDSK “DD: VOL=SER=WTVS1R,UNIT=3330, 
/7 DLBL KSDS,'CUSTOMER.K', » VSAM 11 DSN=LOADKSDS ,DISP=( OLD, KEEP), 
77 EXTENT SYSO10,WTVSAM 11 DCB=(RECFM=FB, LRECL=200 ,BLKSIZE=1609 
77 ASSGN SYSO010,DISK,VOL=WTVSAM» SHR  Z7KSDS DD DSN=CUSTOMER.K,DISP=OLD 
77 EXEC IDCAMS,SIZE=AUTO //SYSPRINT DD SYSOUT=A 
REPRO - //SYSIN DD * | 
INFILE (SQDSK - | REPRO - 
ENV (RECFM (FB) - INFILE (SQDSK) - 
BLKSZ (1600) - OUTFILE (KSDS) 
RECSZ (200) - i* 


PDEV (3330)) = 
) = 
OUTFILE (KSDS) - 


REPLACE 
/& 
DOS/VS example Coutput): © OS/7VS_ example Coutput): 
IDCOO05I NUMBER OF RECORDS PROCESSED WAS 3000 IDCOO05I NUMBER OF RECORDS PROCESSED WAS 3000 


IDCOOO1LI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX..COND.CODE WAS 0 


| LISTCAT output of this object is shown later in section 7.9.2 


DOS/VS notes: 

“@ Access Method Services needs complete specifications of any 
nonvVSAM data set. 

° REPLACE means that in case the output KSDS contains records, 


those input records with matching keys will REPLACE the records 
in the KSDS (could have been omitted like in OS/VS). | 
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7.6.3 PRINT KSDS 


This example shows a partial printout of the KSDS cluster. 


DOS/VS example (Cinput): OS/VS example Cinput): 
// JOB PRINT KSDS (PARTIAL) //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL KSDS, 'CUSTOMER.K',,VSAM //7PRIM0062 EXEC PGM=IDCAMS 
// EXTENT SYSO010,WTVSAM //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
//7 ASSGN SYS010,DISK, VOL=WTVSAM,» SHR //KSDS OD DSN=CUSTOMER .K,DISP=OLD 
//7 EXEC IDCAMS,SIZE=AUTO ~ //SYSPRINT DD SYSOUT=A 
PRINT INFILE (KSDS) - //SYSIN DD * 
CHAR ~ PRINT INFILE (KSDS) - 
COUNT (5) CHAR ~ 
/& COUNT (5) 
/*® 
DOS/VS example Coutput): OS/VS example Coutput): 
LISTING OF DS -CUSTOMER.K | LISTING OF DS -CUSTOMER.K 
KEY OF RECORD - 10 KEY OF RECORD - 10 
10 PHOENIX JOHNSON 10 PHOENIX JOHNSCY 
KEY OF RECORD - 20 KEY OF RECORD - 20 
20 NEW YORK ROBERTS 20 NEW YORK ROBERTS 
KEY OF RECORD - 30 KEY OF RECORD - 30 
30 SAN JOSE NIXON 30 SAN JOSE NIXON 
KEY OF RECORD - 40 KEY OF RECORD - 40 
40 SAN FRANCISCO BURTON 40 SAN FRANCISCO BURTON 
KEY OF RECORD - 50 | KEY OF RECORD - 50 
50 RENO SMITH 50 RENO SMITH 
IDCO005I NUMBER OF RECORDS PROCESSED WAS 5 IDCO005I NUMBER OF RECORDS PROCESSED WAS 5 


IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
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7.6.4 ALTERNATE INDEXES AND PATHS TO KSDS 


7.6.4.1 EXPLANATION OF THE MOST IMPORTANT PARAMETERS 


= 
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KEYS 


RELATE 


UNIQUEKEY/NONUNIQUEKEY 


UPDATE/NOUPDATE 


UPGRADE/NOUPGRADE 


specifies the size and offset of the 
alternate key field, which must be 
included in each base cluster record 
Cand in case of a spanned record, in 
the first segment). 


The alternate key can overlap or be 
contained entirely with another 


(alternate or prime) key field. It 


must consist of a contiguous field. 


specifies the base cluster this 
alternate index belongs to. The base 
cluster can be a nonreusable ESDS or 
KSDS cluster. 


specifies, whether an alternate key 
may occur only once in a base cluster 
record (UNIQUE) or whether more than 


one occurrences are allowed (NONUNI- 
QUEKEY). 


If NONUNIQUEKEY is used (see figure 13 
on page 33) it has to be taken into 
consideration (if the base cluster is 
a KSDS), that for each occurrence the 
prime Key is stored in full length in 
the alternate index data receLd 
adjacent to the alternate key, so the 


alternate index RECORDSIZE should te 


specified large enough. 


For an ESDS base cluster 4 bytes RBA 
are stored for each occurrence. 


1s a PATH parameter and specifies, 
whether an alternate index belonging 
to the upgrade set (see UPGRADE) is to 
be updated (when necessary) or not 
(further details see section 2.7.4 on 
page 35). 


specifies whether an alternate 
index is automatically updated by VSAM 
when base cluster records are insert- 


ed, deleted or when the alternate key 
field ais changed (provided the base 


cluster is not accessed via a path 
With the NOUPDATE attribute. 
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> ie 


6.4.2 DEFINE AIX, DEFINE PATH 


i 


(7 
// 
17 
// 
ff 
(7 
77 
// 
/f 


(& 


DOS/VS example Cinput): 


JOB DEF AIX 'SALESMAN' + PATH 'SALES.CUST' 


DLBL KSDS, 'CUSTOMER.K', » VSAM 
EXTENT SYS010,WTVSAM 
DLBL AIXK1,'SALESMAN.K’»»,VSAM 
EXTENT SYS010,WTVSAM 
DLBL PATHKL, 'SALES.CUST.K',,VSAM 
EXTENT SYS010,WTVSAM 
ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
EXEC IDCAMS,SIZE=AUTO 
DEF AIX ©€ 
NAME (SALESMAN.K) 
FILE (AIXK1) 
RELATE (CUSTOMER.K) 
KEYS (12 40) 
VOL (WTVSAM) 
CYL (1 1) 
IMBD 
NONUNIQUEKEY 
UPGRADE 
) 
DATA ( 
NAME (SALESMAN.K.D) 
CISZ (4096) 
FSPC (20 10) 
) 
INDEX ( 
NAME (SALESMAN.K.1) 
) 


CAT (PRIMER .UCATI1/UCATUPDT ) 


DEF PATH ( 
NAME (SALES.CUST.K) 
FILE (PATHK1) 
PATHENTRY (SALESMAN.K) 
UPDATE 
) 


CAT (PRIMER .UCAT1/UCATUPDT ) 


Output listing is shown on 
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OS/VS example Cinput): 


77PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//7PRIMO072 EXEC PGM=IDCAMS 


//STEPCAT DD DOSN=PRIMER.UCAT1,DISP=SHR 


//7ATXK1 DD VOL=SER=WTVSAM, DISP=OLD,UNIT=3330 
/7SYSPRINT DD SYSOUT=A 


/7SYSIN DD * 
DEF AIX 


DATA 


INDEX 


DEF PATH 


/* 


( 

NAME (SALESMAN.K) 
FILE (AIXK1) 

RELATE (CUSTOMER .K) 
KEYS (12 40) 

VOL C(WTVSAM) 

CYL (1 1) 

IMBD 

NONUNTQUEKEY 
UPGRADE 

) 

( 

NAME (SALESMAN.K.D) 
CISZ (4096) 

FSPC (20 10) 

) | 

( 

NAME (SALESMAN.K.T) 
) 


CAT (PRIMER .UCAT1/UCATUPDT ) 


{ 
NAME (SALES.CUST.K) 
FILE (AIXK1) 

UPDATE 


PATHENTRY (SALESMAN.K) 


) 


{ 


CAT (PRIMER .UCAT1/UCATUPDT ) 


next page 
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DOS/VS_ example (output): OS/VS_ example Coutput) : 


eux THIS IS THE OUTPUT OF DEFINE AIX HH HHH exexee THIS IS THE OUTPUT OF DEFINE AIX *KKex 


IDCOS508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 
TDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 


Oo So 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


xxeKR THIS IS THE OUTPUT OF DEFINE PATH *xxx% *HHRRK THIS IS THE OUTPUT OF DEFINE PATH xX 


TIDCOS520I CATALOG RECOVERY VOLUME IS WTVSAM IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOQO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


LISTCAT output of this object is shown later in section 7.9.2 | 


Notes: 


112 


KEY specifies the length and the offset of the key in the 
record. That is the length and position (relative to zero) of 
the alternate key in the base cluster record. 


NONUNIQUEKEY means that a secondary Key may point to more than 
one primary record (synonyms). 


This AIX will be in the UPGRADE set of the base cluster 
CUPGRADE is default), i.e. it will be automatically updated 
Whenever records in the base cluster are addedvdeleted or a 
secondary key field is modified, and if the PATH accessing the 
base cluster has the UPDATE option (default). 


The DATA CISZ is difficult to determine because of the NONUNI- 
QUEKEY option. But even if specified too small, it would be 
accepted since the data records of an AIX are in spanned format 
(SPANNED is default). 


PATHENTRY indicates the name of the AIX this path refers to. 


The DATA RECSZ can be omitted (default is 4086 32600) for 
average and maximum. The actual size can be computed concider- 
ing that a data record of any AIX must account for five bytes 
Cheader) plus the length of the alternate Key plus one (CUNIQUE- 


KEY) to ‘n't CNONUNIQUEKEY) times the length of the primary Key 


(KSDS base cluster) or times four bytes (RBA length for an ESDS 
base cluster). 


The FILE parameter is required (not for MVS, also see section 
7.2.1 on page 88). The same DD-statement can be used (for 
DEFINE AIX and DEFINE PATH. 


The notes are continued on the next page. 
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DOS/VS notes: 


TJSYSUC is stored in the STDLABEL area. 


The FILE parameters are required to address the CRA of the 
recoverable user catalog. The same set of DLBL, EXTENT, and 
ASSGN statements can be used in further jobs to access the data 
sets since they have the file-ID parameter already coded. 


The ‘volid’' in the path's EXTENT refers to the first volume of 
the index component of the KSDS base cluster, or for an ESDS, 
to the first volume containing the data component of the ESDS 
base cluster, to allocate the volume with the CRA containing a_ 
copy of the catalog entries for this object. 


7.6.4.3 BLDINDEX AIX ON KSDS 


DOS/VS example (input): OS/VS example Cinput): 
7/7 JOB BUILD AIX SALESMAN-CUSTOMER.K ON KSDS /7/7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
77 OLBL KSDS, 'CUSTOMER.K',,VSAM /7PRIMO082 EXEC PGM=IDCAMS 
// EXTENT SYS010,WTVSAM //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
// OLBL AIXK1, 'SALESMAN.K',»VSAM /7/KSDS DD DSN=CUSTOMER.K,DISP=OLD 
// EXTENT SYSO010,WTVSAM /(BIXK1 DD DSN=SALESMAN.K»,DISP=OLD 
// ASSGN SYS010,DISK, VOL=NTVSAM, SHR //SYSPRINT DD SYSOUT=A 
// EXEC IDCAMS,SIZE=AUTO //SYSIN DD * 

BLDINDEX INFILE (KSDS) - BLDINDEX INFILE (KSDS) 
OUTFILE (AIXKL) OUTFILE (AIXK1) 
7& /* 

DOS/VS example (Coutput): — OS/VS example Coutput): 

IDC0652I SALESMAN.K BUILT IDC0652I SALESMAN.K BUILT 


IDCO0O01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCOO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


To create the AIXs, the BLDINDEX function uses a sort which 
will normally be executed in virtual storage, but if Access 
Method Services cannot obtain enough virtual storage (or if 
EXTERNALSORT is specified), BLDINDEX automatically defines two 
ESDS files ina VSAM space controlled by the same or of a 
different catalog, uses them as work files for the external 
sort and deletes them at the end of sort. The default ‘'dnames' 
are IDCUT!1 and IDCUT2Z. | 


DOS/VS notes: 


If external sort is used, two sets of DLBL/EXTENTsS (no EXTENT, 
only volume information needed) must be provided. They can be 
stored in the label area. The default ‘dnames' are IDCUT1 and 
IDCUTZ. | . 
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7.6.4.4 PRINT AIX 


DOS/VS example Cinput): OS/VS example (input): 
/7 JOB PRINT AIXK1 (PARTIAL) //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
7/7 OLBL AIXK1, 'SALESMAN.K', » VSAM //PRIMO092 EXEC PGM=IDCAMS 
// EXTENT SYSO10,WTVSAM //STEPCAT DD DSN=PRIMER.UCAT1 ,DISP=SHR 
//7 ASSGN SYS010,DISK,VOL= WTVSAM»SHR //AIXK1 DD DSN=SALESMAN.K,DISP=OLD 
7/7 EXEC IDCAMS,SIZE=AUTO ; //SYSPRINT DD SYSOUT=A 
PRINT INFILE (AIXK1) - //SYSIN DD * : 
CHAR ~ 7 PRINT INFILECAIXK1) - 
| COUNT (5) : | CHAR - 
/& COUNT (5) 
/* 


Output of Access Method Services (DOS/VS and OS/VS are similar): 


LISTING OF DS -SALESMAN.K 


KEY OF RECORD - ASH | | 
eee ASH 70 1120 1330 1610 1990 2130 3180 3390 3670 4050 4190 5240 5450 5730 6110 6250 7// 
10 9360 9570 98501007011120113301161011990121301318013390136 701405014190152401545015730161101625017// 
1019360195701985020070211202133021610219902213023160233902367024050241 90252402545025730261102625027// 
10293602957029850 
KEY OF RECORD - ASPINALL 
eee ASPINALL © 300 930 1710 2040 2360 2990 3770 4100 4420 5050 5830 6160 6480 7110 7890 8220 8// 
SUT EERO One Te ee Unc tent Loren eat tees Done sme s ore regLonaur lax re je aecoron tuna l Urea Orusyecuatvenay 
70241002442025050258302616026480271102789028220285402917029950 
KEY OF RECORD - BAXTER | 
....+BAXTER 350 1210 1650 1980 2410 3270 3710 4040 4470 5330 5770 6100 6530 7390 7830 8160 8// 
101165011960124101327013710140401447015330157701610016530175901753016160185901945019690203502121021// 
10240402447025330257702610026530273902783028160285902 945029890 
KEY OF RECORD - BOOTH 
--+.-BOOTH 530 920 1220 1600 1800 2020 2590 2980 3280 3660 3860 4080 4650 5040 5340 5720 5// 
00 7780 7980 8200 8770 9160 9460 984010530109201122011600118001202012590129801328013660138601408014// 
201614016 710171001740017780179801820018770191601946019840205302092021220216002180022020225902298023// 
50250402534025720259202614026 710271002 740027 780279802820028770291602946029840 
KEY OF RECORD - BURTON 

..-- BURTON 40 740 1050 1760 2100 2800 3110 3820 4160 4860 5170 5880 6220 6920 7230 7940 8// 
4010740110501176012100126001311013820141601486015170158801622016 92017230179401828018980192902000020// 
002280023110238202416024860251 70258802622026920272302794028280289802929030000 
IDCOO05I NUMBER OF RECORDS PROCESSED WAS 5 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
Note: The output lines were truncated on the right side due to 


limited page size. 
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mo 


7.6.4.5 PRINT PATH 


DOS/VS example (Cinput): 


77 JOB PRINT PATHK1 (PARTIAL) 
/7 DLBL PATHKL, 'SALES.CUST.K'» »VSAM 


7/7 EXTENT SYS010,WNTVSAM 


// ASSGN SYSO10,DISK, VOL=WTVSAM,SHR 


7/7 EXEC IDCAMS, SIZE=AUTO 


PRINT INFILE (PATHK1) - 


7& 


CHAR 


COUNT (5) 


DOS/VS example Coutput): 


LISTING OF DS -SALES.CUST.K 


KEY OF RECORD - 
70 
KEY OF RECORD 
1120 
KEY OF RECORD 
1330 
KEY OF RECORD 
1610 
KEY OF RECORD 
1990 


ASH 
ASH 
ASH 
ASH 


ASH 


WICHITA ASH 
ALBANY ASH 
SEATTLE ASH 
OAKLAND | ASH 


NEW ORLEANS ASH 


IDCOO005I NUMBER OF RECORDS PROCESSED WAS 5 


OS/VS example (Cinput): 


/77PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//7PRIMO102 EXEC PGM=IDCAMS 


//7STEPCAT DD DOSN=PRIMER.UCAT1,DISP=SHR 
//PATHK1 DD DSN=SALES.CUST .K,DISP=OLD 
77SYSPRINT DD SYSOUT=A 


//SYSIN DD * 


PRINT INFILE (PATHK1) 


CHAR 


COUNT (5) 


3 


OS/VS example Coutput): 


LISTING OF DS ~SALES.CUST.K 


KEY OF RECORD - ASH 
70 
KEY OF RECORD - ASH 
1120 
KEY OF RECORD - ASH 
1330 
KEY OF RECORD - ASH 
1610 
KEY OF RECORD - ASH 
1990 


WICHITA 


ALBANY 


SEATTLE 


OAKLAND 


NEW ORLEANS 


ASH 


ASH 


ASH 


ASH 


ASH 


IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 5 
IDCOO0O01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE kAS 0 


IDCQ002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE HAS 0 
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(1 
Cf 
// 
11 
1/ 
// 
Vf 
7/ 
17 


7% 


DOS/VS example (input): 


JOB DEF AIX 'CITY' + PATH ‘CITY.CUST' 
DLBL KSDS, 'CUSTOMER.K', » VSAM 
EXTENT SYSO10,WTVSAM 
DLBL AIXK2,'CITY.K'»»VSAM 
EXTENT SYSO10,WTVSAM 
DLBL PATHK2, ‘CITY.CUST.K', , VSAM 
EXTENT SYS010,WTVSAM 
ASSGN SYS010,DISK, VOL=WTVSAM, SHR 
EXEC IDCAMS, SIZE=AUTO 
DEF AIX ( 
NAME (CITY.K) 
FILE (AIXK2) 
RELATE (CUSTOMER.K) 
KEYS (15 25) 
VOL (WTVSAM) 
CYL (1 1) 
IMBD 
NONUNIQUEKEY 
UPGRADE 
) 
DATA ( 
NAME (CITY.K.D) 
CISZ (4096) 
FSPC (20 10) 
) 
INDEX ( 
NAME (CITY.K.I) 
) 


CAT (PRIMER.UCATI/UCATUPDT ) 


DEF PATH ( 
NAME (CITY.CUST.K) 
FILE (PATHK2} 
PATHENTRY (CITY .K) 
UPDATE 
) 


CAT (PRIMER .UCATI/UCATUPDT ) 


7.6.4.6 DEFINE AIX, DEFINE PATH 


OS/VS example (input): 


/7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//PRIMO122 EXEC PGM=IDCAMS | 
//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
//KIXK2 DD VOL=SER=WTVSAM, DISP=OLD ,UNIT=3330 
//SNSPRINT DD SYSOUT=A 
//SNSIN DD * 
DEF AIX ( - 
NAME (CITY.K) - 
FILE (AIXK2) 2 
RELATE (CUSTOMER.K) - 
KEYS (15 25) - 
VOL (WTVSAM) - 
CYL (1 1) - 
IMBD - 
NONUNIQUEKEY : 
UPGRADE _ 
} as 
DATA ( 2 
NAME (CITY.K.D) 7 
CISZ (4096) : 
FSPC (20 10) = 
} os 
INDEX ¢ = 
NAME (CITY.K.1) si 
} ea 
CAT (PRIMER .UCATI/UCATUPDT ) 
DEF PATH ( : 
NAME (CITY.CUST.K) = - 
FILE (AIXK2) : 
UPDATE - 
PATHENTRY (CITY.K)  - 
} -_ 
CAT (PRIMER.UCAT1/UCATUPDT } 
7*® 


Output listing is shown on next page | | 


a, 
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See 


DOS/VS example (Coutput): 


%*xNM THIS IS THE OUTPUT OF DEFINE AIX HH 
IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 


¥*¥x**% THIS IS THE OUTPUT OF DEFINE PATH **%% 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 


IDCo0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 


OS/VS example (Coutput): 


eeKEM THIS IS THE OUTPUT OF DEFINE AIX *¥HX 
IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 


HH THIS IS THE OUTPUT OF DEFINE PATH HHH HIE 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1LI FUNCTION COMPL., HIGHEST COND.CODE WAS 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 


LISTCAT output of this object is shown later in section 7.9.2 


Note: see notes in section 7.6.4.2 on page 111. 


7.6.4.7 BLDINDEX ATX ON KSDS 


DOS/VS example (input): 


// JOB BUILD AIX CITY-CUSTOMER.K ON KSDS 
// OLBL KSDS, 'CUSTOMER.K',,VSAM 
// EXTENT SYSO010,WTVSAM 
// DLBL AIXK2,'CITY.K‘,,VSAM 
/7 EXTENT SYSO10,WTVSAM 
/7 ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
77 EXEC IDCAMS,SIZE=AUTO 
BLDINDEX INFILE (KSDS) - 
OUTFILE (AIXK2) 
/& 


DOS/VS example (Coutput): 


IDCO652I CITY.K BUILT 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO0O02T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


OS/VS example (input): 


/7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 

//7PRIMO132 EXEC PGM=IDCAMS 

//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 

//KSDS DD DSN=CUSTOMER.K,DISP=OLD 

//AIXK2 DD DSN=CITY.K,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

/7SYSIN DD * | 

BLDINDEX INFILE (KSDS) 

OUTFILE (AIXK2) 

3 


OS/VS example (Coutput): 


IDC0652eI CITY.K BUILT 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: see notes in section 7.6.4.3 on page 113. 
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7.6.4.8 PRINT PART OF AN AIX 


DOS/VS example Cinput): OS/VS example (input): 
// JOB PRINT AIXK2 (PARTIAL) | //7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
7/7 DLBL AIXK2,'CITY.K', VSAM //PRIMO1G2 EXEC PGM=IDCAMS 
7/ EXTENT SYSO10,WTVSAM _- Z7STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
// ASSGN SYS010,DISK;VOL=WTVSAM,SHR | //7AIXK2 DD DSN=CITY.K,DISP=OLD 
// EXEC IDCAMS, SIZE=AUTO //7SYSPRINT DD SYSOUT=A 
| PRINT INFILE (AIXK2) ~ //7SYSIN DD * 
CHAR | - PRINT INFILE CAIXK2) - 
COUNT (3) CHAR | - 
1& | | COUNT (3) 
/% 


Output of Access Method Services (DOS/VS and OS/VS are similar): 


LISTING OF DS -CITY.K 


KEY OF RECORD - ALBANY : 

we.» ALBANY 260 770 1120 2320 2830 3180 4380 4890 5240 6440 6950 7300 8500 9010 93601026// 
131801438014890152401644016950173001850019010193602026020770211202232022830231802438024890252402644// 
29360 | 

KEY OF RECORD - ATLANTA 

eee ATLANTA 520 1840 2580 3900 4640 5960 6700 8020 87601052011840125801390014640159601670// 
-— 2258023900246402596026 7002802028760 

KEY OF RECORD - AUSTIN 

. 2. AUSTIN 280 620 790 1420 1670 2060 2340 2680 2850 3480 3730 4120 4400 4740 4910 554// 
(6970 7600 7850 8240 8520 8860 9030 9660 9910102801062010790114201167012060123401268012850134801373// 
155401579016180164601680016 970176001 785018240185201886019030196601991020280206202079021420216702206// 
237 302412024400 24740249102554025790261802646026800269702 76002 7850282402852028860290302966029910 | 
IDCOOOS5I NUMBER OF RECORDS PROCESSED WAS 3 

IDCO0001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCOO002ZI IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: The output lines were truncated on the right side due to 
limited page size. 
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7.6.4.9 


DOS/VS example (Cinput): 


// JOB PRINT PATHK2 (PARTIAL) 

// DLBL PATHK2, 'CITY.CUST.K', »VSAM 

// EXTENT SYSO10,WTVSAM 

// ASSGN SYS010,DISK, VOL=WTVSAM; SHR 

//7 EXEC IDCAMS,SIZE=AUTO 

PRINT INFILE (PATHK2) - 

CHAR - 
COUNT (5) 

7% 


DOS/VS example (Coutput): 


LISTING OF DS -CITY.CUST.K 


KEY OF RECORD - ALBANY 

260 ALBANY SMITH 
KEY OF RECORD - ALBANY 

770 ALBANY REYNOLDS 
KEY OF RECORD - ALBANY 

1120 ALBANY ASH 
KEY OF RECORD ~ ALBANY 

2320 ALBANY SMITH 
KEY OF RECORD - ALBANY 

2830 ALBANY REYNOLDS 


IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 5 


PRINT PART OF A BASE CLUSTER VIA PATH 


OS/VS example Cinput): 


//7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

7/PRIMO152 EXEC PGM=IDCAMS 

//STEPCAT OD DSN=PRIMER.UCAT1,DISP=SHR 

//7PATHK2 OD DSN=CITY.CUST.K,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 
PRINT INFILE (PATHK2 ) 

CHAR - 


COUNT (5) 


CC® 


OS/VS example Coutput): 


LISTING OF DS -CITY.CUST.K 
KEY OF RECORD - ALBANY 


260 ALBANY SMITH 
KEY OF RECORD - ALBANY 

770 ALBANY REYNOLDS 
KEY OF RECORD - ALBANY 

1120 | ALBANY ASH 
KEY OF RECORD - ALBANY 

2320 ALBANY SMITH 
KEY OF RECORD - ALBANY 

2830 ALBANY REYNOLDS 


IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 5 


IDCOO001IT FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCQOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCOO02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
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7.6.4.19 


REPRO (COPY DATA OF A KSDS TO A SAM-FILE ON DISK) 


DOS/VS_ example Cinput): | OS/VS example (input): 


//7 JOB REPRO KSDS TO SAM-DISK 7 //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL KSDS,'CUSTOMER.K',,VSAM sy | — 77PRIMO162 EXEC PGM=IDCAMS a 
7/7 EXTENT SYSO1LO,WTVSAM | : | //7STEPCAT DD DSN=PRIMER.UCAT1 ,DISP=SHR 
// ASSGN SYS010,DISK, VOL=WTVSAM, SHR | //KSDS DD DSN=CUSTOMER.K,DISP=OLD > 
// DLBL REPKSDS, 'REPRO.KSDS' //7REPKSDS DD VOL=SER=WTVSIR ,UNIT=3330; 
//7 EXTENT SYS000,D0S30Z,1,0,6707,95 // SPACE=(CYL,(551));5 
//7 ASSGN SYS000 ,DISK,VOL=D0S30Z,SHR // | DSN=REPRO.KSDS,DISP=(NEW,KEEP), 
/7 EXEC IDCAMS,SIZE=AUTO | // DCB=(RECFM=FB,LRECL=200 ,BLKSIZE=4000 ) 
REPRO INFILE (KSDS) | = //SYSPRINT DD SYSOUT=A | 
OUTFILE (REPKSDS = //7SYSIN DD * 
ENV (BLKSZ (4000) - REPRO INFILE (KSDS) - 
RECSZ (200) ~ OUTFILE (REPKSDS } 
RECFM (FB) = /* 


PDEV (3330)) - 
; | 


7k 
DOS/VS example Coutput): OS/VS example Coutput): 
IDCOO0O05I NUMBER OF RECORDS PROCESSED WAS 3000 IDCOOQO5I NUMBER OF RECORDS PROCESSED WAS 3000 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO0O02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


DOS/VS note: 


° Access Method Services needs complete specifications of any 
nonvVSAM data set. 
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7.6.4.11 ALTER (FREE SPACE, PASSWORD) 


The three examples given below would probably not be used in a real 
application. They show three different goals which can be achieved 
with ALTER. 


7/ 
// 
// 
// 
7 
17 
eA 


7% 


IDCOO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCOOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


Modify the FREESPACE definition in the data component of a 
cluster after it has been loaded (also see section 8.4 on page 
199). 


Protect a cluster with a master password. 
Nullify password protection. 
Since amaster password is established by the second ALTER 


command, the following one has to specify that password to 
alter the data set attributes. 


DOS/VS example (input): 


JOB ALTER KSDS 
DLBL KSDS, 'CUSTOMER.K*»,VSAM 
EXTENT SYS010,WTVSAM 
DLBL KSDSD, 'CUSTOMER.K.D',,VSAM 
EXTENT SYS010,WTVSAM 
ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
EXEC IDCAMS,SIZE=AUTO 
ALTER CUSTOMER.K.D 
FILE (KSDSD) 
FREESPACE (20 20) 
ALTER CUSTOMER.K 
FILE (KSDS) 
MASTERPW (KSDSMRPW) 
ALTER CUSTOMER .K/KSDSMRPH 
FILE (KSDS) 
NULLIFY (MRPW) 


DOS/VS example (output): 


OS/VS example Cinput): 


77PRIMER JOB WTSC,IBM,MSGLEVEL=1 
/7PRIMO1L72 EXEC PGM=IDCANS 
//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
7/KSDS DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
ALTER CUSTOMER.K.O = 
FILE (KSDS) - 
FREESPACE (20 20) 
ALTER CUSTOMER.K = 
FILE (KSDS) ~ 
MASTERPW (KSDSMRPW) 
ALTER CUSTOMER .K/KSDSMRPW 
FILE (KSDS) - 
NULLIFY (MRPW) 


/*® 


~OS/VS example Coutput): 


IDCOS31I ENTRY CUSTOMER.K.D ALTERED 

IDCOOOLI FUNCTION COMPL.», HIGHEST COND.CODE WAS 0 
IDCO531I ENTRY CUSTONER.K ALTERED 

IDCOOO1I FUNCTION COMPL.», HIGHEST COND.CODE WAS 0 
IOCO531I ENTRY CUSTOMER.K ALTERED 

TOCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


IpcoooerI IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: the FILE parameter is required (not for MVS, also see section 


7.2.1 on page 88). 
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7.6.4.12 


EXPORT A KSDS AND ITS AIX'S _ 


When EXPORT PERMANENT is specified, the exported elastase: Awe: err 
subordinate objects will be deleted from the VSAN- catalog after the. 
EXPORT. For this reason, all AIX's must be exported before the 

base cluster itself. ot a ee | | ~ * = 


DOS/VS example Cinput): | 


7/7 JOB EXPORT AIXK1 + AIXK2 + KSDS 0 /7PRIMER “JOB WTSC,IBM, MSGLEVEL= 1 
/7 DLBL KSDS,'"CUSTOMER.K', »VSAM — SAPRIMOL82 EXEC PGM=IDCAMS. | 
77 EXTENT SYSOLO,WTVSAM AA STEPCAT DD DSN=PRIMER .UCATL, DISP= SHR | 
77 OLBL AIXK1, 'SALESMAN. K') ,VSAM | . wes 77AIXK1 DD DSN=SALESMAN.K,DISP=OLD 
77 EXTENT SYSO1O,WTVSAM | Me /7RIXK2 DD DSN=CITY.K,DISP=OLD 
77 DLBL AIXK2,'CITY.K',,VSAM =< —s—s—=—s—SsSKSDS ~~ DSNECUSTOMER.K,DISP=OLD 
7? EXTENT SYSO1O,WTVSAM | — =o - /7EXPAXK1 DD VOL= ( ;RETAIN) » » SER= 057454), 
7/7 ASSGN SYSO10,DISK,VOL=WTVSAM,SHR = ss ss | ZZ ——sCUUNTT=3400-6,LABEL=(2,SL), 0 | 
// TLBL TAPEOUT,'KSDS.AIXK1.AIXK2' = 77s SNSEXPORTED.AIXK1,DISP=(NEW,PASS) 
77 ASSGN SYSO05,TAPE,VOL=057454 === —ss—s—<S~sS VEXPAXKZ~= DD VOLE (RETAIN, » »SER= 057454) » 
“77 MTC REW,SYSO05 | AP UNITS 3400-6 LABEL=(3,5L), 
77 EXEC IDCAMS,SIZESAUTO rr re) oe oe -DSN=EXPORTED. AIXK2 ,DISP=(NEW, PASS) - 
EXPORT | SALESMAN.K = ZZEXPKSDS DD VOL=( RETAIN, » »SER=057454), 
INFILE (AIXKL) (= 40 UNIT#3400-6 LABEL=(4,5L), | 
OUTFILE (TAPEOUT = = st 77s DSNSEXPORTED. KSDS,DISP= (NEW, PASS) % 
ENV (BLKSZ (4096) = - ~——s //SYSPRINT DD SYSOUT=A_ 
PDEV (24003) nas te F _ //8YSIN— OD Ho ae mee 
| } we EX RORT - SALESMAN, Re fo athe 
: PERMANENT = sss—s—ss NE ATXKE 
EXPORT) = CITY.K QUT FELE CEXPAXKL) = 
| INFILE (AIXK2) oh re oe ee PERMANENT a 
QUTFILE (TAPEOUT sss = EXPORT CITY. se ee 
ENV (BLKSZ (4096) = NL (AIXK2) See 5 oe 
PDEV (2400)) = a ak OUTFILE ( EXPAXK2 } Baa 2883 
| Pe gh ene AR eno & 1g MPERMANENT: =e Gee 
- PERMANENT = EXPORT CCUSTOMER-K 
EXPORT  CUSTOMER.K we NBILE (KSDS) 
| INFILE (KSDS)) - 2 QUTFILE CEXPKSDS) == 
OUTFILE (TAPEOUT) = = RERMANENT ore: 
ENV (BLKSZ (4096) =H 
| PDEV (24002) = 
» a 
PERMANENT 
7% 
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DOS/VS example (Coutput): 


*¥** THIS IS THE OUTPUT OF THE FIRST EXPORT xxx 


IDCO5941 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCOOOL1T 


PORT. DS CREATED ON 10/20/77 AT 15:57:18 
ENTRY (R) SALES.CUST.K DELETED 

ENTRY (G) SALESMAN.K DELETED 

ENTRY (D) SALESMAN.K.D DELETED 

ENTRY (I) SALESMAN.K.I DELETED 

FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


**** THIS IS THE OUTPUT OF THE SECOND EXPORT *%xx 


IDCO5941 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCOOO1I 


PORT. DS CREATED ON 10/20/77 AT 15:57:28 
ENTRY (R) CITY.CUST.K DELETED 

ENTRY (G) CITY.K DELETED 

ENTRY (D) CITY.K.D DELETED 

ENTRY (I) CITY.K.I DELETED 

FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


**¥*% THIS IS THE OUTPUT OF THE THIRD EXPORT ***x 


IDC05941 
IDCO5501 
IDCO5501 
IDCO5501 
IDCOOO1I 


rocoo02r 


PORT. DS CREATED ON 10/20/77 AT 15:57:37 
ENTRY (C) CUSTOMER.K DELETED 

ENTRY (D) CUSTOMER.K.D DELETED 

ENTRY (1) CUSTOMER.K.I DELETED 

FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


DOS/VS notes: 


OS/VS example (Coutput): 


*H¥¥* THIS IS THE OUTPUT OF THE FIRST EXPORT **%* 


IDCO5941 
IOCO550I 
IDCO5501 
IDCOS5501 
IDCOS550I1 
IDCOOOL1T 


PORT. DS CREATED ON 12/21/77 AT 21:32:52 
ENTRY (R) SALES.CUST.K DELETED 


ENTRY (D) SALESMAN.K.D DELETED 


ENTRY (1) SALESMAN.K.I DELETED 
ENTRY (G) SALESMAN.K DELETED 
FUNCTION COMPL., HIGHEST COND.CODE WAS 9 


xxx* THIS IS THE OUTPUT OF THE SECOND EXPORT *x* 


IDCO5941 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCOOOLT 


PORT. DS CREATED ON 12721777 AT 21:32:57 
ENTRY (R) CITY.CUST.K DELETED 

ENTRY (D) CITY.K.0 DELETED 

ENTRY (I) CITY.K.I DELETED 

ENTRY (G) CITY.K DELETED 

FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


*¥*% THIS IS THE OUTPUT OF THE THIRD EXPORT xx 


IDCO5941 
IDCO5501 
IDCO5501 
IDCO5501 
IDCOOOLT 


Ipco0de!I 


PORT. DS CREATED ON 12/21/777 AT 21:33:03 
ENTRY (D) CUSTOMER.K.D DELETED 

ENTRY (1) CUSTOMER.K.I DELETED 

ENTRY (C) CUSTOMER.K DELETED 

FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


e Since standard tape label processing is used (no unlabeled 
tapes allowed prior to DOS/VS Rel. 34), the output tape 
contains these files : 

1. VOL + HDR-label 
2. AIXK1 data 

3. EOF label 

U. HDR label 

5. AIXK2 data 

6. EOF label 

7. HDR label 

8. KSDS data 

9. EOF label 

e At EOJ the tape will not be rewound unless REWIND/UNLOAD is 


specified in the ENV-parameter or a 


of 


step. 
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7.6.4.13 IMPORT A KSDS AND ITS _AIX'S 


DOS/VS example (input): OS/VS_ example (input): 
7/ JOB IMPORT KSDS + AIXK1 + AIXK2 //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL KSDS» 'CUSTOMER.K'» » VSAM //PRIMO192 EXEC PGM=IDCAMS | 
77 EXTENT SYS010,WTVSAM //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
77 DLBL AIXK1, 'SALESMAN.K', ,VSAM /7AIXK1 DD _DSN=SALESMAN.K,AMP=' AMORG', 
/7 EXTENT SYS010,WTVSAM ld VOL=SER=WTVSAM,DISP=O0LD ,UNIT=3330 
7/7 DLBL AIXK2,'CITY.K', »VSAM SAATXK2 DD DSN=CITY.K,AMP='AMORG', 
/7 EXTENT SYS010,WTVSAM J VOL=SER=WTVSAM, DISP=OLD , UNI T=3330 
// ASSGN SYSO010,DISK, VOL=HTVSAM; SHR 7/7KSOS DD DSN=CUSTOMER.K,AMP='AMORG', 
77 TLBL TAPEIN, 'KSDS.AIXKL.AIXK2' 1 VOL=SER=NTVSAM, DISP=OLD ,UNIT=3330 
7/ ASSGN SYSO004, TAPE», VOL=057454 /7EXPAXK1L OD VOL=( RETAIN, »»SER=057454),_ 
/7 MTC REW,SYS004¢ 7 UNIT=3400-6,LABEL=(2,SL), 
7/7 MTC FSF ,»SYS004,6 | MW DSN=EXPORTED.AIXK1 ,DISP=( OLD, PASS) 
/7 EXEC IDCAMS, SIZE=AUTO  /7EXPAXK2 DD VOL=( sRETAIN, » »SER=057454), 
IMPORT INFILE (TAPEIN - 4/ UNIT=3400-6,LABEL=(3,SL), 
ENV (BLKSZ (4096) = - 1 DSN=EXPORTED .AIXK2 ,DISP=( OLD , PASS) 
PDEV (2400)) = - /7EXPKSDS DD VOL=( RETAIN, » »SER=057454), 
) - ff i UNIT=3400-6, LABEL=(4,SL), 
OUTFILE (KSDS) i 11 DSN=EXPORTED .KSDS,DISP=(OLD, PASS) 
CAT (PRIMER.UCAT1/UCATUPDT ) //SYSPRINT DD SYSOUT=A 
7& /7SYSIN DD * | 
// MTC REW,SYS004 7 IMPORT INFILE (EXPKSDS) © - 
/7 EXEC IDCAMS, SIZE=AUTO | OUTFILE (KSOS) | - 
IMPORT INFILE (TAPEIN | - | — CAT (PRIMER .UCAT1/UCATUPDT ) 


ENV (BLKSZ (4096) 
PDEV (2400)) 


IMPORT INFILE (EXPAXK1) = 
OUTFILE (AIXK1) - 


) = CAT (PRIMER.UCATI/UCATUPDT ) 

OUTFILE (AIXK1) - IMPORT INFILE (EXPAXK2) = 

CAT (PRIMER.UCAT1/UCATUPDT ) OUTFILE (AIXK2) ” 

IMPORT INFILE (TAPEIN | - CAT (PRIMER .UCAT1/UCATUPDT ) 
ENV (BLKSZ (4096) “ /* 


PDEV (2400)) 

) : = 
OUTFILE (AIXK2) - 
CAT (PRIMER.UCATI/UCATUPDT } 


/& 


Output listing is shown on next page 
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DOS/VS example Coutput): 


¥*¥% THIS IS THE OUTPUT OF THE SECOND IMPORT 


IDC0604I DS BEING IMP. WAS EXP. 10/20/77 AT 15:57 
IDCG520T CATALOG RECOVERY VOLUME IS WTVSAM 

IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IDCOOOLI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


¥*¥*% THIS IS THE OUTPUT OF THE SECOND IMPORT x 


IDCO0604I DS BEING IMP. WAS EXP. 10/20/77 AT 15:57 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 

IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


**¥* THIS IS THE OUTPUT OF THE THIRD IMPORT *x* 


IDC06041 
Ipco5201 
IDCO5081 
IDCO5091 
IDCoooll 


DS BEING IMP. WAS EXP. 10/20/77 AT 15:57 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


e The PURGE parameter is not 


OS/VS example (Coutput): 


**¥*% THIS IS THE OUTPUT OF THE FIRST IMPORT **x* 


IDCO604I DOS BEING IMP. WAS EXP. 12721777 AT 21:33 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAN 

IDCOS508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IDCOO0O01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


exe THIS IS THE OUTPUT OF THE SECOND IMPORT **x* 


IDCO604I DS BEING IMP. WAS EXP. 12/21/77 AT 21:32 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 

IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IDCOQO1I FUNCTION COMPL.», HIGHEST COND.CODE WAS 0 


*¥***% THIS IS THE OUTPUT OF THE THIRD IMPORT **x* 


Iocoé04I 
IDCO5201 
IDCO5081 
IDCO5091 
IDCooO1l 


DS BEING IMP. WAS EXP. 12/21/77 AT 21:32 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 9 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 90 
FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 9 


required because no expiration date 


was specified in the DEFINE command. 


e Read also section A.6.2 on page 258 where IMPORT considerations 


are described. 


e Since an AIX cannot 


the KSDS IMPORT. 


DOS/VS notes: 


° To import the KSDS, 
at the beginning of the KSDS 


be built 
cluster is loaded or imported, 


imported before its base 
jobstream has to start with 


or 
the 


the input tape must be precisely positioned 


HDR1i-label with a MTC FSF command 


(see DOS/VS notes in the previous section £for the tape layout). 


e After the KSDS 


read the AIX's data. This 


command between the two jobsteps. 
DOS/VS Rel.34 and up) 


parameter (available for 


has been imported, the tape must 


be rewound to 
can only be done by aMTC REW 
The REWIND option of the ENV 
cannot be used 


Since it would rewind the tape at both OPEN and CLOSE times and 


lose the positioning. 
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7.6.4.14 VERIFY KSDS - 


DOS/VS example (Cinput): OS/VS example Cinput): 


// JOB VERIFY KSDS | | - //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//7 OLBL KSDS, 'CUSTOMER.K', »VSAM | s //PRIMO202 EXEC PGM=IDCAMS 
//7 EXTENT SYSO10,WTVSAM | _ Z/7STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
// ASSGN SYS010,DISK,VOL=NTVSAM, SHR /7/KSDS DD DSN=CUSTOMER.K,DISP=OLD 
7/7 EXEC IDCAMS,SIZE=AUTO 7/SYSPRINT DD SYSOUT=A 
VERIFY FILE (KSDS) | //SYSIN DD 
/& | - VERIFY FILE (KSDS) 
if) 
DOS/VS example Coutput): OS/VS example Coutput): 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 
° The condition code '0' shows that the VERIFY ‘function worked | 
properly. | i 


If the data set was in need of VERIFYing, messages IDC3300I and 
IDC3351I will be issued. 


° The FILE parameter is required to identify the DD statement 
describing the data set to be verified. 
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7.7 ESDS CENTRY SEQUENCED DATA SET? 


7.7.1 DEFINE ESDS 


DOS/VS example (input): OS/VS example Cinput): 

// JOB DEFINE ESDS IN VSAM SPACE //7PRIMER JOB WTSC,IBM»MSGLEVEL=1 

// DLBL ESDS, 'CUSTOMER.E'»,VSAM //PRIMO2Z12 EXEC PGM=IDCAMS 

//7 EXTENT SYSO1O,WTVSAM //7STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 

// ASSGN SYSO010,DISK,VOL=HTVSAM, SHR //ESDS DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 

/?7 EXEC IDCAMS,SIZE=AUTO , //SYSPRINT 0D SYSOUT=A 

DEF CLUSTER ~ //SYSIN DD * | 
( - DEF CLUSTER - 
NAME (CUSTOMER.E) - ( ~ 
FILE (ESDS) - NAME (CUSTOMER.E) ~ 
VOL (WTVSAM) - FILE (ESDS) ~ 
CYL (5 2) - VOL (WTVSAM) - 
NONINDEXED ~ CYL (5 2) - 
) - NONINDEXED ~ 
DATA ( - ) - 
NAME (CUSTOMER.E.D) - DATA ( - 
RECORDSIZE (200 200) - NAME (CUSTOMER.E.D) - 
CISZ (4096) - RECORDSIZE (200 200) - 
) - CISZ (4096) - 
CAT (PRIMER .UCATL/UCATMRPW) ) - 
/& CAT (PRIMER .UCAT1/UCATUPDT } 
/* 
DOS/VS example Coutput): OS/VS example Coutput): 


IDCO5081I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 IDCOS508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCO0001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO0O02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 
° NONINDEXED is the parameter to specify a DEFINE ESDS. 


e See also section 7.6.1 on page 106. 


DOS/VS notes: 
° IJSYSUC is stored in the STDLABEL area. 


. The VSAM data set name in the DLBL statement is optional for 
DEFINE. : 
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7.7.2 REPRO (LOAD AN ESDS) 


DOS/VS example (Cinput): | . OS/VS example (input): 


//7 JOB LOAD ESDS FROM DISK-SAM /7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL SQDSK, 'LARGE.ESDS.DATA' /7PRIMO222 EXEC PGM=IDCAMS 
77 EXTENT SYS00055>56802,95 7 7/STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
// ASSGN SYS000,DISK, VOL=DOS30Z,SHR //7SQDSK DD VOL=SER=WTVSLR,UNIT=3330; 
/7 OLBL ESDS, 'CUSTOMER.E',»VSAM 17 DSN=LOADESDS,DISP=(OLD,KEEP), 
// EXTENT SYSO10,HTVSAM // DCB=(RECFM=FB, LRECL=200,BLKSIZE=1600) 
//7 ASSGN SYS010,DISK,VOL=WTVSAM, SHR /7ESDS DD DSN=CUSTOMER.E,DISP=OLD 
77 EXEC IDCAMS,SIZE=AUTO //SYSPRINT DD SYSOUT=A 
REPRO //SYSIN DD * 
INFILE (SQDSK = REPRO = 
ENV (RECFM (FB) - INFELE (SQDSK) ~ 
BLKSZ (1600) - OUTFILE (ESDS) 
RECSZ (200) = /® 


PDEV (3330)) = 
} | a 
OUTFILE (ESDS) 


/& 
DOS/VS example (Coutput): OS/VS example Coutput): 
IDCOOOSI NUMBER OF RECORDS PROCESSED WAS 3000 IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 3000 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDC0001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


DOS/VS notes: 


° Access Method Services needs complete specifications of any 
nonVSAM data set. 
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7.7.2.1 DEFINE AIX, DEFINE PATH 


DOS/VS example Cinput): OS/7VS example (Cinput): 
// JOB DEF AIX 'SALESMAN' + PATH 'SALES.CUST' //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// OLBL ESDS, 'CUSTOMER.E',,VSAM //PRIMO232 EXEC PGM=IDCAMS 
7/7 EXTENT SYSO10,WTVSAM 7/STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR | 
// DLBL AIXEL, 'SALESMAN.E'; »VSAM //KIXEI DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
//7 EXTENT SYSO010,WTVSAM //SYSPRINT DO SYSOUT=A 
7/7 OLBL PATHE], 'SALES.CUST.E',,VSAM //SYSIN DD * 
// EXTENT SYS010,NTVSAM DEF AIX ( - 
77 BSSGN SYSO10,DISK,VOL=WTVSAM, SHR NAME (SALESMAN.E) - 
//7 EXEC IDCAMS,SIZE=AUTO FILE (AIXE1) ~ 
DEF AIX ( ~ RELATE (CUSTOMER.E) - 
NAME (SALESMAN.E) - KEYS (12 40) es 
FILE (AIXE1) - VOL (WTVSAM) - 
RELATE (CUSTOMER.E) ~ CYL (1 1) - 
KEYS (12 40) - IMBD = 
VOL (WTVSAM) - NONUNIQUEKEY ~ 
CYL (1 1) - UPGRADE | ~ 
IMBD - } - 
NONUNIQUEKEY - DATA ( - 
UPGRADE ~ NAME (SALESMAN.E.D) = - 
) - CISZ (4096) - 
DATA ¢ - FSPC (20 10) - 
NAME (SALESMAN.E.D) ~ ) - 
CISZ (4096) - INDEX ( ~ 
FSPC (20 10) - NAME (SALESMAN.E.I) = - 
} ~ ) - 
INDEX ( ~ CATALOG (PRIMER.UCAT1/UCATMRPH) 
NAME (SALESMAN.E.I) - DEF PATH ( ~ 
) - NAME (SALES.CUST.E) = - 
CAT (PRIMER .UCATI/UCATMRPW) FILE (AIXE1) - 
DEF PATH ( - UPDATE oe 
NAME (SALES.CUST.E) - PATHENTRY (SALESMAN.E) - 
FILE (PATHEL) - ) - 
PATHENTRY (SALESMAN.E) ~ | CATALOG (PRIMER .UCATI1/UCATMRPH ) 
UPDATE - /* 


) e 
CAT (PRIMER .UCAT1/UCATMRPW } 
/ & 


Output listing is shown on next page 
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xexHM THIS IS THE OUTPUT OF DEFINE AIX *x¥%%% 


IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO509I INDEX ALLOC.STAT. 


DOS/VS example Coutput): 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


*¥*X THIS IS THE OUTPUT OF DEFINE PATH *¥%#% 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


FOR VOLUME WTVSAM IS 0 


OS/VS example (Coutput): 
xx THIS IS THE OUTPUT OF DEFINE AIX 3%» 
IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCOSO09I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1I FUNCTION COMPL.,. HIGHEST COND.CODE WAS 0 


xxRHK THIS IS THE OUTPUT OF DEFINE PATH xx 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS C 


LISTCAT output of this object is shown later in section 7.9.2 


Note: see notes in section 7.6.4.2 on page 111. 


7.7.2.2 BLDINDEX ATX ON ESDS 


/ 
// 
7 
// 
// 
// 
// 


7 & 


DOS/VS example Cinput): 


JOB BUILD AIX SALESMAN-CUSTOMER.E ON ESDS 

DLBL ESDS,'CUSTOMER.E',,VSAM 

EXTENT SYS010,NTVSAM 

DLBL AIXE1, 'SALESMAN.E', ,VSAM 

EXTENT SYS010,WTVSAM 

ASSGN SYS010,DISK,VOL=WTVSAM, SHR 

EXEC IDCAMS,SIZE=AUTO 

BLDINDEX INFILE (ESDS) 

OUTFILE (AIXE1) 


DOS/VS example Coutput): 


IDC0652I SALESMAN.E BUILT 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


OS/VS example (Cinput): 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 
77PRIMO242 EXEC PGM=IDCAMS : 
//7STEPCAT DD DSN=PRIMER.UCAT1 ,DISP=SHR 
/7ESDS DD DSN=CUSTOMER.E,DISP=O0LD 
//AIXE1 DD DSN=SALESMAN.E,DISP=OLD 
//7SYSPRINT DD SYSOUT=A 


| Z/7SYSIN DD * 


BLDINDEX INFILE (ESDS) -~ 
OUTFILE (AIXE1) 
/* 


OS/VS example Coutput): 


IDCO652T SALESMAN.E BUILT 
IDCOO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCoo02eT IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: see notes in section 7.6.4.3 on page 113. 
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7.7.2.3 PRINT ESDS 


DOS/VS example Cinput): | OS/VS example (input): 

// JOB PRINT ESDS (PARTIAL) ~ 7 //PRIMER JOB WTSC,IBM,MSGLEVEL=1 

// DLBL ESDS,'CUSTOMER.E',,VSAM sits of 7PRIMO572 EXEC PGM=IDCAMS 
7/7 EXTENT SYS010,NTVSAM | //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 

//7 ASSGN SYSO10, DISK, VOL=WTVSAM, SHR 7/ESDS DD DSN=CUSTOMER.E,DISP=OLD 

7/ EXEC IDCAMS, SIZE=AUTO //SYSPRINT DD SYSOUT=A 

PRINT INFILE (ESDS) ~ //SYSIN DD * 
CHAR - PRINT INFILE (ESDS) ~ 
COUNT (5) | CHAR ~ 
/% | | COUNT (5) 
[* 
DOS/VS example: Coutput): OS/VS example (output): 

LISTING OF DS -CUSTOMER.E | | LISTING OF DS -CUSTOMER.E 

RBA OF RECORD - 0 RBA OF RECORD - 0 

6000s” | MIAMI FLEMING 6000 MIAMI FLEMING 
RBA OF RECORD - 200 | | RBA OF RECORD - 200 
20 NEW YORK ROBERTS 20 NEW YORK ROBERTS 
RBA OF RECORD - 400 | RBA OF RECORD - 400. 

16000 MIAMI FLEMING 16000 MIAMI FLEMING 
RBA OF RECORD - 600 7 RBA OF RECORD - 600 | 

50 RENO SMITH «50 RENO SMITH 

RBA OF RECORD - 800 | 7 RBA OF RECORD - 800 
60 HOUSTON JACKSON 60 HOUSTON JACKSON 
IDCOOOS5I NUMBER OF RECORDS PROCESSED WAS 5 IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 5 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 
IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IpCoo02T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
Note: 


° Since data loaded into the ESDS base cluster are not the same 
used in examples of section 7.6 Con page 106) for the KSDS base 
cluster, the listings will differ as well. 
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7.7.2.4 


PRINT AIX 


DOS/VS example Cinput): 


/7 JOB PRINT AIXE1 (PARTIAL) 


77 DLBL AIXE1, 'SALESMAN.E',,»VSAM 
// EXTENT SYSO10,WTVSAM 


77 ASSGN SYSO10,DISK,VOL=WTVSAM, SHR 
7/7 EXEC IDCAMS;,SIZE=AUTO 
PRINT INFILE (AIXE1) 


7 & 


DUMP 


COUNT (3) 


OS/VS example Cinput): 


7/7PRIMER 


//7PRIMOZ52 EXEC PGM=IDCAMS 


JOB WTSC,IBM,MSGLEVEL=1 


7/7STEPCAT DD DOSN=PRIMER.UCAT1,DISP=SHR 
DD DSN=SALESMAN.E ,DISP=OLD 
7/SYSPRINT DD SYSOUT=A 


//AIXEL 


/7SYSIN 


DD * 


PRINT INFILE (CESDS) 


7*® 


DUMP 


COUNT (3)} 


Output of Access Method Services (DOS/VS and OS/VS are similar): 


LISTING OF DS -SALESMAN.E | 
KEY OF RECORD - C1E2C8404040404040404040 


0000 
0020 
0040 
0060 
0080 
00A0 
00co 
OOEO 
0100 
0120 


00040048 
580000AC 
E800013A 
20000183 
28000254 
B8000317 
980003A9 
DO000558 
60000607 
980007F9 


OcclE2cs 
800000AD 
2800013A 
E80001CA 
FO00025B 
00000318 
60000437 
98000559 
D00006D8 
60000958 


40404040 
48000118 
F000013B 
280001CA 
BS&0002D2 
98000319 
D0000438 
600005B7 
980006D9 
B800095D 


40404040 
B8000110 
BS0001AB 
FOOOO1CB 
58000203 
60000362 
98000439 
DOO0005B8 
60000767 
4800095E 


KEY OF RECORD ~ C1E2D7C9D5C103D340404040 


0000 
0020 
0040 
0060 
0080 
0OA0 
ooco 
OOEO 


00040039 
c8000082 


10000190 00000193 


B0000227 
600003FA 


—O00006BA 


100007DE 
G80008FE 


OCC1E2D7 
58000083 


08000209 
280003FA 
FOOOO6BC 
D800086D 
LOOOOSFE 


C9D5C103 
E8000100 
20000196 
600002DA 
FOO0048E 
800006BE 
4800086E 
D800094A 


D3404040 
00000103 
4000019C 
280002DA 
1000048E 
1000074A 
1LO00086E 
2800094B 


KEY OF RECORD - C2C1E7E3C5D9404040404040 


0000 
0020 
0040 
0060 
0080 
COAO 
00co 
OOEO 


00040039 
C8000103 
48000287 
B800035C 
F000043C 
DG000598 
G80006AE 
D8000860 


occecle7 
E8000107 
00000289 
800003AA 
8000043E 
98000599 
1000073C 
00000860 


E3C5D940 
08000190 
6000028A 
FOO0003AC 
10000478 
6000059A 
8000073D 
C8000945 


40404040 
C8000193 
FOOOO31A 
800003AE 
98000479 
2800061E 
4800073E 
78000946 


40000004 
4800011E 
BS80001AD 
B8000242 
200002D3 
58000363 
600004C7 
98000589 
D0000768 
D8 


40000075 
20000106 
8000019D 
FOO0036E 
D8000490 
F000074C 
D8o000sBC 
B&800094D 


40000076 
E8000197 
F0000310 
1L00003E8 
6000047A 
D8000620 
100007CC 
40000947 


IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 3 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: The 
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BOOOOO0SsE 
D&000122 
G80001AE 
58000243 
E80002EA 
20000363 
DO0O0004C8& 
60000647 
96000769 


78000077 


4000010C 
S800019E 
1000036E 
OOOO051E 
8000074E 
800008BE 
48 


40000078 
O80001FA 
48000320 
980003E9 
28000506 

00000620 
800007CD 
08 


were truncated 


D8000090 


58000123 
D80001B2 
20900243 
280002EA 


E80003A7 


980004C9 
DO0006468 
600007F7 


DOOO007A 
8000010D 


10000222 


D8000370 
LOOOOSIE 
100007DD 
100008C0 


9800007A 
280001FB 
0000035A 
600003EA 
40000507 
C80006AC 
480007CE 


on the 


cg000092 
20000123 
580001B3 
E800025A 
FOOO0ZEB 
D00003A8 
60000557 
98000649 
DOO0O7FS 


28000080 
4800010E 
58000224 
000003F9 
D8000520 
480007DE 
OO0008FD 


FO000100 
BSO0001FD 
FO00035B 
2800043A 
08000507 
800006AD 
LOOOOS5E 


right side 
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due to 


7.7.2.5 PRINT PATH 


DOS/VS example (Cinput): 


/7 JOB PRINT PATHE] (PARTIAL) 
/7 DLBL PATHE], 'SALES.CUST.E',,VSAM 
/7 EXTENT SYSO010,WTVSAM 
// ASSGN SYS010,DISK; VOL=NTVSAM, SHR 
// EXEC IDCAMS,SIZE=AUTO 
PRINT INFILE (PATHEL) 

CHAR 

COUNT (5) 
/& 


DOS/VS example Coutput): 


LISTING OF DS ~SALES.CUST.E 
KEY OF RECORD - ASH 


70 WICHITA 
KEY OF RECORD - ASH 
4050 NEW ORLEANS 
KEY OF RECORD - ASH 
14050 NEW ORLEANS 
KEY OF ‘RECORD ~- ASH 
24050 NEW ORLEANS 
KEY OF RECORD - ASH 
10070 WICHITA 


ASH 


ASH 


ASH 


ASH 


ASH 


IDCOOO05I NUMBER OF RECORDS PROCESSED WAS 5 


OS/VS example Cinput): 


/7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//PRIMO262 EXEC PGM=IDCAMS 


//STEPCAT DD DSN=PRIMER .UCAT1,DISP=SHR 
//PATHEL DD DSN=SALES.CUST.E,DISP=OLD 


//SYSPRINT DD SYSOUT=A 
/7S3VSIN DD * 
PRINT INFILE (PATHE) 
CHAR 
COUNT (5) 
(¥® 


OS/VS example Coutput): 


LISTING OF DS -SALES.CUST.E 
KEY OF RECORD - ASH 


70 WICHITA 

KEY OF RECORD - ASH 

4050 NEW ORLEANS 
KEY OF RECORD - ASH 

14050 NEW ORLEANS 
KEY OF RECORD - ASH 

24050 NEW ORLEANS 
KEY OF RECORD - ASH 

10070 WICHITA 


ASH 


ASH 


ASH 


ASH 


ASH 


IDCOQO005I NUMBER OF RECORDS PROCESSED WAS 5 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 9% 
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7.7.2.6 DEFINE AIX, DEFINE PATH 


/ 
// 
// 
// 
1/ 
// 
(7 
// 
7 


7% 
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DOS/VS example Cinput): 


JOB DEF AIX 'CITY' + PATH ‘CITY-CUST' 


DLBL ESDS, 'CUSTOMER.E',,VSAM 
EXTENT SYS010,WTVSAM 

DLBL AIXE2,'‘CITY.E's»VSAM 
EXTENT SYS010,NTVSAM 


DLBL PATHE2, 'CITY.CUST.E', ,VSAM 


EXTENT SYS010,WTVSAM 


ASSGN SYS010,DISK,VOL=NTVSAM, SHR 


EXEC IDCAMS,SIZE=AUTO 


DEF AIX 


DATA 


INDEX 


DEF PATH 


( 
NAME (CITY.E) 
FILE (AIXE2) 


RELATE (CUSTOMER.E) 


KEYS (15 25) 
VOL (WTVSAM}) 
CYL (1 13 

IMBD 
NONUNIQUEKEY 
UPGRADE 

) 

( 

NAME (CITY.E.D) 
CISZ (4096) 
FSPC (20 10) 

) 

( 

NAME (CITY.E.1) 
) | 


CAT (PRIMER .UCAT1/UCATMRPW ) 


( 


NAME (CITY.CUST.E) 


FILE (PATHE2 ) 


PATHENTRY (CITY.E} 


UPDATE 
) 


CAT (PRIMER .UCATI/UCATMRPW ) 


OS/VS example (input): 


//7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//PRIMO272 EXEC PGM=IDCAMS | 
//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR _ 
/(RIXE2 DD VOL=SER=WTVSAM, DISP=OLD ,UNIT=3330 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD ® | 
DEF AIX - 
NAME (CITY.E) ~ 
FILE (AIXE2) ~ 
RELATE (CUSTOMER.E) - 
KEYS (15 25) - 
VOL (WTVSAM) - 
CYL (1 1) z 
IMBD 2 
" NONUNIQUEKEY - 
UPGRADE ~ 
) os 
DATA ( ~ 
NAME (CITY.E.D) - 
CISZ (4096) _ 
FSPC (20 10) - 
) a 
INDEX ( - 
NAME (CITY.E.1) ~ 
) a 
CAT (PRIMER .UCATI1/UCATMRPH ) 
. DEF PATH ( 7 
NAME (CITY.CUST.E) - 
FILE (AIXE2) = 
UPDATE - 
PATHENTRY (CITY.E) - 
) ae 
CAT (PRIMER.UCAT1/UCATMRPH) 
/* 


Output listing is shown on next page 


DOS/VS example Coutput): 


¥*¥H*K* THIS IS THE OUTPUT OF DEFINE AIX 2% 
IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 

IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 


**¥¥*% THIS IS THE OUTPUT OF DEFINE PATH **%%% 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOO0O01I FUNCTION COMPL., HIGHEST COND.CODE WAS 


IDC0002ZI IDCAMS PROC. COMPL. MAX. COND.CODE WAS 


OS/VS example Coutput): 


eexMeH THIS IS THE OUTPUT OF DEFINE AIX xxx 


IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 
IDCO509I INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 

IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 


**¥*HH THIS IS THE OUTPUT OF DEFINE PATH **#% 


IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 


IDC0O002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 


LISTCAT output of this object is shown later in section 7.9.2 


Note: see notes in section 7.6.4.2 on page 


7.7.2.7 BLDINDEX ATX ON ESDS 


DOS/VS example Cinput): 


// JOB BUILD AIX CITY-CUSTOMER.E ON ESDS 
//7 DLBL ESDS, 'CUSTOMER.E',,VSAM 
// EXTENT SYS010,WTVSAM 
// DLBL AIXE2, 'CITY.E'>»VSAN 
77 EXTENT SYSO010,WTVSAM 
//7 ASSGN SYS010,DISK, VOL=NTVSAM, SHR 
7/7 EXEC IDCAMS,SIZE=AUTO 
BLDINDEX INFILE (ESDS) - 
OUTFILE (AIXE2) 
1% 


DOS/VS example Coutput): 


IDCO652eI CITY.E BUILT 


a a 


OS/VS example (Cinput): 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 

7/PRIMO282 EXEC PGM=IDCAMS 

//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 

//ESDS DD DSN=CUSTOMER.E,DISP=OLD 

//KIXE2 DD DSN=CITY.E,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 

BLDINDEX INFILE (ESDS) 

OUTFILE (AIXE2) 

(* 


OS/VS example Coutput): 


IDCO652I CITY.E BUILT 


IDCOOOLI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 
IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
Note: see notes in section 7.6.4.3 on page 113. 
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7.7.2.8 PRINT AIX 


77 JOB PRINT AIXE2 (PARTIAL) 
/7 DLBL AIXE2,'CITY.E'» »VSAM 
/7 EXTENT SYSO010,WTVSAM 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
//7 EXEC IDCAMS, SIZE=AUTO | 


 & 


PRINT INFILE 
DUMP 


(AIXE2 ) 


COUNT (3) 


DOS/VS example Cinput): 


OS/VS example Cinput): 


//PRIMER 


7 RIXE2 


//7SYSIN 


7 


JOB WTSC,IBM,MSGLEVEL=1 
7/PRIMO292 EXEC PGM=IDCAMS 
7/STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
DD DSN=CITY.E,DISP=OLD 

//SYSPRINT DD SYSOUT=A 


DD * 


PRINT INFILE (AIXE2) — - 
DUMP 
COUNT (3) 


Output of Access Method Services (DOS/VS and OS/VS are similar): 


LISTING OF DS -CITY.E 
KEY OF RECORD - C1D3C2C1D5E8404040404040404040 


0000 
0020 
0040 
0060 
0080 
0040 
00co 


0004002D OFC1D3C2 
00012258 00012320 
000243E8 00027258 
00030320 000303E8 
00042480 00042578 
00073960 0007C7D0 
OOO8EAFO O00S8EBBS 


C1D5E840 
000123E8 
00027320 


00036258. 


00042640 
0007C898 


40404040 
0001B258 
000273E8 
00036320 
0004B4B0 
00070960 


40404040 
0001B320 
00020258 
000363E8 
00048578 
00085A28 


KEY OF RECORD - C1E3D3C105E3C14040404040404040 
0000 00040018 OFC1E3D3 C1D5E3C1 40404040 40404040 
0020 0004E4B0 0004E578 0004E640 00057258 00057320 
0040 00060640 00069708 000697D0 00069898 00072460 
0060 0007E7D0 0007E898 00087960 00087A28 00087AFO 
KEY OF RECORD - C1EGE2E3C9D5404040404040604040 


0000 
0020 
0040 
0060 
0080 
O0A0 
00C0 
00EO 
0100 
0120 
0140 
0160 


IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 3 


00040057 OFC1EGE2 
O000A3E8 0000A4B0 
0001C4B0 000250C8 
000343E8 000344B0 
00046320 000463E8 
0004¢F258 000523E8 
0005DC80 0005DD48 
00066BB8 00066C80 


0006FD48 00077640 
00078E10 00079000 


00081C80 00081E10 
000897D0 00092320 


E3C9D540 
0000A578 
00025190 
00030578 
00046480 
00052578 
00063ED8 
00066048 
00077708 
00080640 
00082000 
00092578 


40404040 
000130C8 
00025258 
0003D640 
00049320 
00052708 
000640C8 
OO0GEAFO 
000777D0 
00080708 
000893E8 
000927D0 


40404040 
00013190 
0002B0C8 
00030708 
000493E8 
OOOS5AED8 
00064258 
0006EBBS 
00077898 
000807D0 
000894B0 


IDCOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: The 


output lines 


limited page size. 
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000020C8 
0001B3E8 
00020320 
00039258 
0004B640 
OOO0S5AF0 


00004000 
000573E8 
00072578 
00090960 


00005428 
00013258 
0002B190 
00040320 
000494B0 
0005B0C8 
00065898 
0006EC80 
00077960 
00080898 
00089578 


were truncated 


00002190 
00024258 
0002D3E8 
00039320 
00073700 
OO0O085BB8 


000040C8 
000604B0 
00072640 
00090A28 


00005C80 
0001C320 
0002B258 
000403E8 
0004F0C8 
0005B258 
00065960 
0006FBB8 
00077A28 
00080960 
00089640 


on the 


00002258 
00024320 
00030258 
000393E8 
00073898 
OOO8EA28 


00004190 
00060578 
0007E708 
OOO90AFO 


00005EDS8 
O001C3E8 
00034320 
000404B0 
0004F190 
OOOS5DBBS 
00065A28 
0006FC80 
00078C80 
00080A28 
00089708 


right side 
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due to 


7.7.2.9 PRINT PATH 


DOS/VS example Cinput): 


//7 JOB PRINT PATHE2 (PARTIAL) 

// DLBL PATHE2, 'CITY.CUST.E',,VSAM 

/7 EXTENT SYSO10,WTVSAM 

//7 ASSGN SYS010,DISK, VOL=WNTVSAM, SHR 

// EXEC IDCAMS,SIZE=AUTO 

PRINT INFILE (PATHE2) - 
CHAR - 
COUNT (5) 
Ht 


DOS/VS example Coutput): 


LISTING OF DS -CITY.CUST.E 


OS/VS example (input): 


/7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

//PRIMO302 EXEC PGM=IDCAMS 

//STEPCAT DD DSN=PRIMER.UCATL,DISP=SHR 

//PATHE2 DD DSN=CITY.CUST.E,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

/7SXSIN DD * 
PRINT INFILE ( PATHE2) - 

CHAR - 

COUNT (5) 

(* 


OS/VS example (output): 


LISTING OF DS -CITY.CUST.E 


KEY OF RECORD - ALBANY KEY OF RECORD - ALBANY 

9010 ALBANY REYNOLDS 9010 ALBANY REYNOLDS 
KEY OF RECORD - ALBANY KEY OF RECORD - ALBANY 
19010 ALBANY REYNOLDS 19010 ALBANY REYNOLDS 
KEY OF RECORD - ALBANY KEY OF RECORD - ALBANY 
29010 ALBANY REYNOLDS 29010 | ALBANY REYNOLDS 
KEY OF RECORD - ALBANY KEY OF RECORD - ALBANY 

1120 | ALBANY ASH 1120 ALBANY ASH 
KEY OF RECORD - ALBANY KEY OF RECORD - ALBANY 

11120 ALBANY ASH 11120 ALBANY ASH 


IDCOO05I NUMBER OF RECORDS PROCESSED WAS 5 


IDCOOO05I NUMBER OF RECORDS PROCESSED WAS 5 


IDCOOOLI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002IT IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
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7.8 RRDS CRELATIVE RECORD DATA SET) 


7.8.1 DEFINE RRDS 


DOS/VS example Cinput): _ OS/VS_ example Cinput): 
// JOB DEFINE RRDS IN VSAM SPACE . Z/7PRIMER =: JOB: WTSC,, IBM, MSGLEVEL=1 
77 DLBL RRDS, 'CUSTOMER.R's » VSAM - Z7PRIMO312 EXEC PGM=IDCAMS | 
//7 EXTENT SYSO10,WTVSAM | 7/STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
7/7 ASSGN SYSO10,DISK,VOL=WTVSAM, SHR 7/RRDS DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
// EXEC IDCAMS, SIZE=AUTO | | //SYSPRINT DD SYSOUT=A_ 
DEF CLUSTER 7 //SYSIN DD * 
( - | DEF CLUSTER | - 
NAME (CUSTOMER.R) - _ a a! | - 
FILE (RRDS) - : NAME (CUSTOMER.R) : 
VOL (WTVSAM) - _——_ FILE (RRDS) - 
CYL (5 2) oe 7 VOL (WTVSAM) - 
NUMBERED - CYL (5 2) - 
) | _— 7 NUMBERED ~ 
DATA ( | - 5 7 - 
NAME (CUSTOMER.R.D)  - DATA | - 
RECORDSIZE (80 80) - a NAME (CUSTOMER.R.D) = - 
CISZ (4096) - a RECORDSIZE (80 80) = = 
} - a | CISZ (4096) - 
CAT (PRIMER .UCAT1/UCATMRPW) | ) | - 
1% | | CAT: « C PRIMER .UCAT1/UCATUPDT ) 
| i oe : , 
DOS/VS example (output): ss OSVVS_ example Coutput): 


IDCOS508I DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 IDCO508I DATA ALLOC. STAT. FOR VOLUME WTVSAN IS 0 
IDCO520I CATALOG RECOVERY VOLUME IS WTVSAM IDCO520I CATALOG RECOVERY. VOLUME IS WTVSAM | 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL. >» HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


cas 


¢ ° NUMBERED is the parameter to specify to define an RRDS. 


° See also notes in section 7.6.1 on page 106. 
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7.8.2 REPRO (LOAD AN RRDS) 


DOS/VS example Cinput): | OS/VS example Cinput): 

// JOB LOAD RRDS FROM DISK-SAM /7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

77 DLBL SQDSK,'RRDS.DATA' | //PRIMO322 EXEC PGM=IDCAMS 

77 EXTENT SYS000>5»» 14693519 //STEPCAT DD DSN=PRIMER.UCAT1 ,DISP=SHR 

// ASSGN SYS000,DISK, VOL=D0S30Z,SHR //SQDSK = DD -VOL=SER=WTVSIR,UNIT=3330, 

//7 DLBL RRDS,'CUSTOMER.R'»»VSAM 17 DSN=LOADRRDS ,DISP=(OLD,KEEP), 

7/7 EXTENT SYS010,WTVSAM 11 DCB=(RECFM=FB, LRECL=80 ,BLKSIZE=1600) 

/7 ASSGN SYS010,DISK, VOL=WTVSAM; SHR 7/RRDS DD DSN=CUSTONER .R»DISP=OLD 

// EXEC IDCAMS,SIZE=AUTO //SYSPRINT DD SYSOUT=A 

REPRO - //SYSIN = ODD 
INFILE (SQDSK - REPRO - 

ENV (RECFM (FB) - INFILE (SQDSK) - 
BLKSZ (1600) - OUTFILE (RRDS) 
RECSZ (80) - /* 


PDEV (3330)) . < 
) a 
OUTFILE (RRDS} 


/& 
DOS/VS example Coutput): OS/VS example Coutput): 
IDCOO05I NUMBER OF RECORDS PROCESSED WAS 206 IDCOO05I NUMBER OF RECORDS PROCESSED WAS 206 


IDCOO0O1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL.», HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: 


° REPLACE is only used for RRDS to RRDS copy. 


DOS/VS note: 


e Access Method Services needs complete specifications of any 
nonVSAM data set. 
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7.9 LISTCAT 


7.9.1 LISTCAT NAME 


DOS/VS example Cinput): 


77 JOB LIST UCAT NAME 
// DLBL IJSYSUC, 'PRINER.UCAT1',,VSAM 
// EXTENT SYS010,WTVSAM ; 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
// EXEC IDCAMS,SIZE=AUTO 
LISTCAT NAME ~ 
CAT (PRIMER.UCAT1/UCATMRPW) 


/& 
DOS/VS example (Coutput): 
LISTING FROM CATALOG -- PRIMER.UCAT1 
AIX ----------- CITY.E 
DATA ~------- CITY.E.D 
INDEX ------ CITY.E.I 
PATH ------- CITY.CUST.E 
AIX ----------- CITY.K. 
DATA ~--~--- CITY.K.D 
INDEX ------ CITY.K.I 
PATH ------- CITY .CUST.K 
CLUSTER ------- CUSTOMER.E 
DATA ~------ CUSTOMER.E.D 
CLUSTER ------- CUSTOMER .K 
DATA ~------ CUSTOMER.K.D 
INDEX ------ CUSTOMER .K.I 
CLUSTER ------- CUSTOMER.R 
DATA ------~- CUSTOMER .R.D 
CLUSTER ------- PRIMER.UCATL | 
DATA ------- VSAM. CATALOG.BASE.DATA.RECORD 
INDEX ------ VSAM. CATALOG.BASE . INDEX.RECORD 
AIX ----------- SALESMAN.E 
DATA ------- SALESMAN.E.D 
INDEX ------ SALESMAN.E.I 
PATH ~------- SALES.CUST.E 
AIX ----------- SALESMAN.K 
DATA ------~-- SALESMAN.K.D 
INDEX ------ SALESMAN.K.I 
_ PATH ------- SALES.CUST.K 
VOLUME -------- WTVSAM 


OS/VS example Cinput): 


/7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 
/7/PRIMO332 EXEC PGM=IDCAMS 
//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
//SYSPRINT DD SYSOUT=A | 
//SYSIN DD * | 
LISTCAT NAME - 
CAT (PRIMER .UCAT1/UCATMRPH) 


(*® 
OS/VS example Coutput): 
LISTING FROM CATALOG -- PRIMER.UCATL 
AIX ----------- CITY.E 
DATA ------- CITY.E.D 
INDEX ------ CITY.E.I 
PATH ------- CITY.CUST.E 
AIX ----------- CITY.K 
DATA ~------ CITY.K.D 
INDEX ------ CITY.K.I 
PATH ------- CITY.CUST.K 
CLUSTER ------- CUSTOMER.E 
DATA ------- CUSTOMER.E.D 
CLUSTER ------- CUSTOMER .K 
DATA ------- CUSTOMER .K.D 
INDEX ------ CUSTOMER .K.I 
CLUSTER ------- CUSTOMER .R 
DATA ~------ CUSTOMER.R.D 
CLUSTER ------- PRIMER.UCATL 
DATA ------- VSAM. CATALOG. BASE .DATA.RECORD 
INDEX ------ VSAM. CATALOG. BASE. INDEX.RECORD 
AIX ----------- SALESMAN.E 
DATA ~------ SALESMAN.E.D 
INDEX ------ SALESMAN.E.I 
PATH ------- SALES.CUST.E 
AIX ----------- SALESMAN .K 
DATA ~------ SALESMAN.K.D 
INDEX ------ SALESMAN.K.I 
PATH ~------ SALES.CUST.K 


VOLUME ~~------~ WTVSAM 


Output listing is continued on next page | 
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THE NUMBER OF ENTRIES PROCESSED WAS: THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX --------~---------- 4 AIX -------+------------ 4 
CLUSTER -~------~------ 4 ALIAS ----------------- 0 

DATA ---~~------~~----- 8 CLUSTER --------------- 4 

INDEX ----------------- 6 DATA ------------------ 8 

NONVSAM --------------- 0 GOG sesso ees ene sc sees 0 

PATH -~-----~----------- 4 INDEX ----------------- 6 

SPACE ----------------- 1 NONVSAM -----~---------- 0 

USERCATALOG ----------- 0 PATH ooveeescasteccetcus 4 

| TOTAL --~~~-~--~------- 27 SPACE ~---~--=-----~--- 1 

THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 USERCATALOG ----------- 0 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 TOTAL ~---------------- 27 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: 


e No catalog password is required, Since it is a read-only 
operation and the various passwords are not to be displayed. 
NAME indicates that only names of objects and its type will be 
listed. 
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7.9. “LISTCAT ALL AND EXPLANATION OF THE FIELDS 


This output has been produced after having defined the USER CATA- 
LOG, the SPACE, loaded the KSDS and built one alternate index (see 
examples page 100 through 115). The values are established by VSAM 
by its own logic and by default. | 


DOS/VS example Cinput): 


7/ JOB LIST UCAT ALL 
// DLBL IJSYSUC, 'PRIMER.UCAT1', » VSAM 
// EXTENT SYS010,WTVSAM 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
77 EXEC IDCAMS, SIZE=AUTO 
LISTCAT ALL - 
CAT (PRIMER .UCAT1/UCATMRPH) 
7k 


OS/VS example (Cinput): 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//7PRIMO112 EXEC PGM=IDCAMS 
//STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
//SYSPRINT DD SYSOUT=A 
7/SYSIN DD * 

LISTCAT ALL - 

CAT (PRIMER.UCAT1/UCATMRPH) 

7* 


Output of Access Method Services (DOS/VS and OS/VS are similar): 


LISTING FROM CATALOG -~- PRIMER.UCAT1 


CLUSTER ------- CUSTOMER .K 
HISTORY 
OWNER-IDENT----~-- (NULL) CREATION--~------- 77.355 RCVY-VOL---------- WTVSAM RCVY-CI-------- X'00000E' 
RELEASE---~------------- 2 EXPIRATION----~--- 00.000 RCVY-DEVT----X'30502009' 
PROTECTION-PSHD---~- (NULL) RACF~-------------~- -(NO) 
ASSOCIATIONS 
DATA----~ CUSTOMER.K.D 
INDEX-~--CUSTOMER .K.I 
AIX------ SALESMAN.K 
DATA ------- CUSTOMER.K.D 
HISTORY | | 
OWNER-IDENT------~- (NULL) CREATION------ ~---77.355 RCVY-VOL---------~- WTVSAM RCVY-CI----~--- X"00000D' 
RELEASE--~----~-~---~-- 2 EXPIRATION~---~---- 00.000 RCVY-DEVT---~-X' 30502009' 
PROTECTION-PSWD---~- (NULL) RACF--~----~--------- (NO) 
ASSOCIATIONS 
CLUSTER--CUSTOMER .K 
ATTRIBUTES 
KEYLEN------------~-~-- 5 AVGLRECL------------- 200 BUFSPACE------------ 4096 CISIZE-------~-----~- 1024 
RKP--------- 0 MAXLRECL-~---~-------- 200 EXCPEXIT---------- (NULL) CI/CA-----~---------- 198 
SHROPTNS(1,3) RECOVERY SUBALLOC NOERASE INDEXED NOWRITECHK IMBED NOREPLICAT 
UNORDERED NOREUSE NONSPANNED 
STATISTICS 
REC-TOTAL-------~--- 3000 SPLITS-CI------------ 0 EXCPS-~------------- 1601 
REC-DELETED--~-~------~ 0 SPLITS-CA------------ 0 EXTENTS----------~------ 1 
REC-INSERTED------~-~-- 0 FREESPACE-/CI-------~-- 20 SYSTEM-TIMESTAMP: 
REC-UPDATED-----------~ 0 FREESPACE-ZCA-~------- 10 X' SBDE7F 92DF1F7800' 
REC-RETRIEVED--~---- 3010 FREESPC-BYTES-~---- 245760 
ALLOCATION 
SPACE-TYPE------ CYLINDER HI-ALLOC-RBA---~-- 1013760 
SPACE-PRI-~------------- 5 HI-USED-RBA------ 1013760 
SPACE-SEC-----~--------- 2 
_ VOLUME | 
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VOLSER------------ WTVSAM PHYREC-SIZE--------- 1024 
DEVTYPE------ X'30502009' PHYRECS/TRK----------- 11 
VOLFLAG------------ PRIME TRACKS/CA-----------~- 19 
EXTENTS: 

LOW-CCHH---~- X'00040000' LOW-RBA---------------- 0 
HIGH-CCHH~---X'00080012' HIGH-RBA--------- 1013759 
INDEX ------ CUSTOMER.K.I 
HISTORY 
OWNER-IDENT------- (NULL) CREATION---------~- 77.355 
RELEASE---------------- 2 EXPIRATION-------- 00.000 
PROTECTION-PSWD----~ (NULL) RACF---------------- (NO) 
ASSOCIATIONS 
CLUSTER--CUSTOMER.K 
ATTRIBUTES 
KEYLEN----------------- 5 AVGLRECL--------------- 0 
RKP--~------------------ 0 MAXLRECL------------ 2041 
SHROPTNS(1,3) RECOVERY SUBALLOC NOERASE 
NOREUSE 
STATISTICS 
REC-TOTAL~------------- 6 SPLITS-CI-------------- 0 
REC-DELETED----------~-- 0 SPLITS-CA-------------- 0 
REC-INSERTED-----~------ 0 FREESPACE-ZCI---------- 0 
REC-UPDATED----------~- 0 FREESPACE-%CA---------- 0 
REC-RETRIEVED---------- 0 FREESPC-BYTES------ 10240 
ALLOCATION 
SPACE-TYPE--------- TRACK HI-ALLOC-RBA------- 22528 
SPACE-PRI-------------- 1 HI-USED-RBA-------- 22528 
SPACE -SEC-------------- 1 
VOLUME 
VOLSER--~---------- WTVSAM PHYREC-SIZE--------- 2048 
DEVTYPE------ X'30502009' PHYRECS/TRK------------ 6 
VOLFLAG---------~-- PRIME TRACKS/CA-------------- 1 
EXTENTS: 
LOW-CCHH----- X'00030011' LOW-RBA---------------- 0 
HIGH-CCHH----X'00030011' HIGH-RBA----------- 12287 
VOLUME 
VOLSER------------ HTVSAM PHYREC-SIZE--------- 2048 
DEVTYPE------ X'30502009' PHYRECS/TRK--~--------- 6 
VOLFLAG------------ PRIME TRACKS/CA------------- 19 
EXTENTS: | 
LOW-CCHH----~- X'00040000' LOW-RBA------~----- 12288 
HIGH-CCHH----X'00080012' HIGH-RBA----------- 22527 
CLUSTER ------- PRIMER .UCAT1 
HISTORY 
OWNER-IDENT-------(NULL) CREATION---------- 77.355 
RELEASE---------------- 2 EXPIRATION-------- 00.000 
PROTECTION 
MASTERPH-------- UCATMRPW UPDATEPW-------- UCATUPDT 
CONTROLPW--------- (NULL) READPH------------ (NULL) 
USAR~------------- ( NONE ) 
ASSOCIATIONS 
DATA----- VSAM. CATALOG. BASE .DATA.RECORD 


INDEX----VSAM.CATALOG.BASE.INDEX.RECORD 
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HI-ALLOC-RBA----- 1013760 EXTENT-NUMBER---------- 1 
HI-USED-RBA------ 1013760 EXTENT-TYPE-------- X'00' 
TRACKS--~~------------ 95 
RCVY-VOL---------- WTVSAM RCVY-CI-------- X'00000F' 
RCVY-DEVT----X' 30502009" 
BUFSPACE--------------- 0 CISIZE-------------- 2048 
EXCPEXIT---------- (NULL) CI/CA------------------ 6 
NOWRITECHK IMBED NOREPLICAT UNORDERED 
EXCPS----------------- 48 INDEX: 
EXTENTS---------------- 2 LEVELS----------------- 2 
SYSTEM-TIMESTAMP: ENTRIES/SECT---------- 14 
X' @BDE7F92DF1F7800' SEQ-SET-RBA-------- 12288 
HI-LEVEL-RBA----------- 0 
HI-ALLOC-RBA------- 12288 EXTENT-NUMBER---------- 1 
HI-USED-RBA--------- 2048 EXTENT-TYPE-------- X'00' 
TRACKS----------------- 1 
HI-ALLOC-RBA------- 22528 EXTENT-NUMBER---------- 1 
HI-USED-RBA-------- 22528 EXTENT-TYPE-------- X80! 
TRACKS----------~----- 95 
CODE-------------- (NULL) RACF---------------- (NO? 
ATTEMPTS~--------------- 2 USVR--------~----- (NULL) 
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VSAM. CATALOG. BASE .DATA. RECORD 


HISTORY | 
OWNER-IDENT~-~--~~- (NULL) CREATION---------- 00.000 
RELEASE soo s2eeseccsesae 2 EXPIRATION-------- 00.000 
PROTECTION-PSWD-----(NULL) RACF---------------- (NO) 
ASSOCIATIONS 
CLUSTER--PRIMER .UCAT1 
ATTRIBUTES 
KEYLEN----~------------ 44 AVGLRECL------------- 505 
RKP-------------- etese 0 MAXLRECL------------- 505 
SHROPTNS(3,3) RECOVERY SUBALLOC NOERASE 
UNORDERED NOREUSE NONSPANNED BIND 
STATISTICS | 
REC-TOTAL Sse ssesecens 15 SPLITSéCioeeweeeneeeccs 0 
REC-DELETED------------ 0: SPLITS-CA--+=--42-55-<- 0 
REC-INSERTED----------- 0 FREESPACE-“CI---------- 0 
REC-UPDATED------------ 0 FREESPACE-%CA---------- 0 
REC-RETRIEVED---------- 0 FREESPC-BYTES----- 218112 
ALLOCATION 
SPACE-TYPE---------TRACK HI-ALLOC-RBA-----~ 225280 
SPACE-PRI-~----------- 33 HI-USED-RBA------- 225280 
SPACESSECeseeiocee see 18 
VOLUME | 
VOLSER------------ WTVSAM PHYREC-SIZE---------- 512 
DEVTYPE-----~X'30502009' PHYRECS/TRK----------- 20 
VOLFLAG------------ PRIME TRACKS/CA-------------- 3 
LON=KEY--s-=5s-t2s45~2 00 
HIGHSKEY=seceeecsseese 3F 
HI-KEY-RBA--~------- 6144 
EXTENTS: 
LOW-CCHH----- X'00010000' LOW-RBA---------------- 0 
HIGH-CCHH----X'0002000A' HIGH-RBA---------- 204799 
VOLUME 
VOLSER------------ WIVSAM PHYREC-SIZE----------512 
DEVTYPE------ X%'30502009' PHYRECS/TRK----------- 20 
VOLFLAG------------ PRIME TRACKS/CA---~----------- 3 
LOWSKEY~oseeHsseeese-- 40 | 
HIGH-KEYoseececcese sss FF 
HI-KEY-RBA-------- 204800 
EXTENTS: 
LOW-CCHH----- X'0002000E' LOW-RBA----------- 204800 
HIGH-CCHH----X'00020010' HIGH-RBA---------- 225279 


INDEX ------ VSAM .CATALOG.BASE .INDEX.RECORD 
HISTORY | 
OWNER-IDENT------- (NULL) CREATION----------00.000 
RELEASE--------~-------- 2 EXPIRATION-------- 00.000 
PROTECTION-PSWD----- (NULL) RACF-------~------~--(NO) 
ASSOCIATIONS 
CLUSTER--PRIMER .UCAT1 
ATTRIBUTES 
KEYLEN---------------- G44 AVGLRECL<-----<---------- 0 
RKP--~--~----~-----~-~-~ 0 MAXLRECL------------- 505 
SHROPTNS( 3,3) RECOVERY SUBALLOC NOERASE 
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BUF SPACE------------ 3072 CISIZE--------------- 512 
EXCPEXIT---------- (NULL) CI/CA----------------- 40 
INDEXED NOWRITECHK IMBED NOREPLICAT 
RECVABLE | 
EXCPS---~------------- 22 
EXTENTS---------------- 2 
SYSTEM-TIMESTAMP: 

X' 8BDE7F4D55E43800' 
HI-ALLOC-RBA------ 204800 EXTENT-NUMBER--~-----~~ 1 
HI-USED-RBA------~-- 20480 EXTENT-TYPE-------- X'00' 
TRACKS~---------------- 30 
HI-ALLOC-RBA------ 225280 EXTENT-NUMBER---------- 1 
HI-USED-RBA------- 225280 EXTENT-TYPE-------- X'00' 
TRACKS----------------- 3 
BUFSPACE---------------0 CISIZE--------------- 512 
EXCPEXIT---------- (NULL) CI/CA--------- -------- 20 
NOKRITECHK IMBED NOREPLICAT UNORDERED 


NOREUSE BIND 
STATISTICS 
REC-TOTAL-------------- 3 SPLITS-CI-------------- 0 EXCPS----------------- 13 INDEX: 
REC-DELETED------------ 0 SPLITS-CA-------------- 0 EXTENTS---------------- 3 LEVELS----------------- 2 
REC-INSERTED----------- 0 FREESPACE-“%CI---------- 0 SYSTEM-TIMESTAMP: ENTRIES/SECT----------- 7 
REC-UPDATED------------ 0 FREESPACE-“%CA---------- 0 X' 8BDE7F4D55E43800' SEQ-SET-RBA-------- 30720 
REC-RETRIEVED~--------- 0 FREESPC-BYTES------ 34816 HI-LEVEL-RBA----------- 0 
ALLOCATION 
SPACE-TYPE--------- TRACK HI-ALLOC-RBA------- 36352 
SPACE-PRI-------------- 3 HI-USED-RBA-------- 36352 
SPACE-SEC-------------- 3 
VOLUME 
VOLSER----~-------- WTVSAM PHYREC-SIZE---------- 512 HI-ALLOC-RBA----~--- 30720 EXTENT-NUMBER---------- ) 
DEVTYPE------ X%'30502009' PHYRECS/TRK----------- 20 HI-USED-RBA---------- 512 EXTENT-TYPE-------- X'00' 
VOLFLAG------------ PRIME TRACKS/CA-------------- 1 
EXTENTS: 
LOW-CCHH----- X'0002000B' LOW-RBA---------------- 0 TRACKS----------------- 3 
HIGH-CCHH----X'0002000D' HIGH-RBA----------- 30719 
VOLUME | 
VOLSER------------ WIVSAM PHYREC-SIZE---------- 512 HI-ALLOC-RBA------- 35840 EXTENT-NUMBER---------- 1 
DEVTYPE---~-- X'30502009' PHYRECS/TRK----------- 20 HI-USED-RBA-------- 31232 EXTENT-TYPE-------- X'80' 
VOLFLAG------------ PRIME TRACKS/CA-------------- 3 
LOW-KEY-------~--~~--- 00 
HIGH-KEY-------------- 3F 
EXTENTS: 
LOW-CCHH----~-- X'00010000' LOW-RBA------------ 30720 TRACKS---------------- 30 
HIGH-CCHH----X'0002000A' HIGH-RBA----------- 35839 
VOLUME 
VOLSER------------ WTVSAM PHYREC-SIZE---------- 512 HI-ALLOC-RBA------- 36352 EXTENT-NUMBER---------- 4 
DEVTYPE------ X%'30502009' PHYRECS/TRK----------- 20 HI-USED-RBA-------- 36352 EXTENT-TYPE-------- X'80! 
VOLFLAG--~--------- PRIME TRACKS/CA-------------- 3 
LOW-KEY------~-------- 40 
HIGH-KEY-------------- FF 
EXTENTS: 
LOW-CCHH----- X'0002000E' LOW-RBA------------ 35840 TRACKS----------------- 3 
HIGH-CCHH----X'00020010' HIGH-RBA----------- 36351 
AIX ----------- SALESMAN.K 
HISTORY | 
OWNER-IDENT-------~ (NULL) CREATION---------- 77.355 RCVY-VOL---------- WTVSAM RCVY-CI-------- X'000010' 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----xX'30502009' 
PROTECTION-PSWD----- (NULL) RACF---------------- (NO) 
ASSOCIATIONS 
DATA----- SALESMAN.K.D 
INDEX----SALESMAN.K.I 
CLUSTER--CUSTOMER.K 
PATH----- SALES .CUST.K 
ATTRIBUTES 
UPGRADE 
DATA ------- SALESMAN.K.D 
HISTORY 
OWNER -IDENT------- (NULL) CREATION---------- 77.355 RCVY-VOL---------- WTVSAM RCVY-CI----~---- X' 000011! 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30502009' 
PROTECTION-PSHD----- (NULL) RACF----------~----- (NO) 
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ASSOCIATIONS 


‘AIX------ SALESMAN.K 
ATTRIBUTES 
KEYLEN---------------- 12 
RKP--------------~----- 5 
AYRM PoeeSe eee ee esecens 40 
SHROPTNS(1,3) RECOVERY 
UNORDERED NOREUSE 
STATISTICS | 
REC-TOTAL------------- 50 
REC-DELETED------------ 0 
REC-INSERTED----------- 0 
REC-UPDATED------------ 0 
REC-RETRIEVED---------- 6 
ALLOCATION 
SPACE-TYPE------ CYLINDER 
SPACE-PRI-------------- 1 
SPACE-SEC-------------- 1 
VOLUME | 
VOLSER------------ WTVSAM 
DEVTYPE------ X' 30502009! 
VOLFLAG------------ PRIME 
EXTENTS: 
LOW-CCHH----- X'00090000' 
HIGH-CCHH----xX'00090012' 
INDEX ------ SALESMAN.K.I 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE--------~----~~-~ 2 
PROTECTION-PSWD----- (NULL) 
ASSOCIATIONS 
AIX------ SALESMAN.K 
ATTRIBUTES 
KEYLEN-~-------------- 12 
RK Penn eee nee eee nnn 5 
SHROPTNS(1,3) RECOVERY 
NOREUSE 
STATISTICS 
REC-TOTAL----------~--- 1 
REC-DELETED------------ 0 
REC-INSERTED-----------0 
REC-UPDATED------------ 0 
REC-RETRIEVED---------- 0 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 1 
SPACE-SEC---~--~-------- 1 
VOLUME 
VOLSER------------ WTVSAM 
DEVTYPE------ X' 30502009! 
VOLFLAG------------PRIME 
EXTENTS: 
LOW-CCHH----- X'00030012' 


HIGH~CCHH-~--~-X'00030012' 
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BUF SPACE------- -----8704 CISIZE-------------- 4096 
EXCPEXIT---------- (NULL) CI/CA----------------- 54 
INDEXED NOWRITECHK IMBED - NOREPLICAT 
EXCPS----------------- 26 
EXTENTS---------------- 1 
SYSTEM-TIMESTAMP: 
X' 8BDE7FB0B33BB800' 
HI-ALLOC-RBA------ 221184 EXTENT-NUMBER---------~- 1 
HI-USED-RBA------- 221184 EXTENT-TYPE-------- X'00' 
TRACKS---------------- 19 
RCVY-VOL---------- WTVSAM RCVY-CI-------- x'000012' 
RCVY-DEVT----X'30502009' | 
BUFSPACE--------------- 0 CISIZE--------------- 512 
EXCPEXIT---------- (NULL) CI/CA----------------- 20 
NOWRITECHK IMBED NOREPLICAT UNORDERED 
EXCPS------------------ 6 INDEX: | 
EXTENTS---------------- 2 LEVELS---------------~- 1 
SYSTEM-TIMESTAMP: ENTRIES/SECT----------- 7 
X' 8BDE7FB0B338B800' SEQ-SET-RBA-------- 10240 
HI-LEVEL-RBA------- 10240 
HI-ALLOC-RBA------- 10240 EXTENT-NUMBER~--------- 1 
HI-USED-RBA------------ 0 EXTENT-TYPE-------- X'00' 


AVGLRECL------------4086 
MAXLRECL-----------32600 
SUBALLOC NOERASE 
SPANNED NONUNIQKEY 
SPLT7S-Cioees-cses5ce22 0 
SPLTTS-CAsaeeseesentuce ) 
FREESPACE-“CI--------- 20 
FREESPACE-“CA~-----~--- 10 
FREESPC-BYTES----- 196608 
HI-ALLOC-RBA------ 221184 
HI-USED-RBA------- 221184 
PHYREC-SIZE---~----- 4096 
PHYRECS/TRK-~----------- 3 
TRACKS/CA------------- 19 
COWS RBAsseedewe tees 0 
HIGH-RBA-----~---- 221183 
CREATION---------- 77.355 
EXPIRATION--------00.000 
RAChatetscetesuecces (NO) 
AVGEREC oseexceeacanece 0 
MAMI REC Lesscaedeeccse 505 
SUBALLOC NOERASE 
SPLT1S=Clessceuncosacen 0 
SPLITS2Cheseeeeeesseees 0 
FREESPACE-ZCI-~-~---~-~ 0 
FREESPACE-/CA---------- 0 
FREESPC-BYTES------10240 
HI-ALLOC-RBA------- 10752 
HI-USED-RBA-------- 10752 
PHYREC-SIZE---------- 512 
PHYRECS/TRK----------- 20 
TRACKS/CAsSe2eeeeeseees 1 
LOW RBAsSeeeseeeseeeoe 0 


HIGH-RBA------ Seeee 10239 
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VOLSER------------ WTVSAM 
DEVTYPE------ X'30502009' 
VOLFLAG------------ PRIME 
EXTENTS: 
LOW-CCHH----- X'00090000' 
HIGH-CCHH-~--X'00090012' 
PATH ------- SALES.CUST.K 
HISTORY 
OWNER-IDENT~-----~ (NULL) 
RELEASE---------------- 2 
-PROTECTION-PSWD----~ (NULL) 
ASSOCIATIONS 
AIX------SALESMAN.K 
DATA~~---SALESMAN.K.D 
INDEX----SALESMAN.K.I 
DATA----- CUSTOMER.K.D> 
INDEX----CUSTOMER.K.I 
ATTRIBUTES 
UPDATE 
VOLUME -------- WTVSAM 
~ HISTORY 
RELEASE----------------2 
CHARACTERISTICS 
BYTES/TRK---------- 13165 
TRKS/CYL~-------------19. 
CYLS/VOL------------- 411 
DATASPACE | 
DATASETS~-~-~-~ owen nnn 3 
EXTENTS---------------- 1 
_. SEC-ALLOC~------------- 1 
TYPE--~---------CYLINDER 
EXTENT-DESCRIPTOR: 
TRACKS-TOTAL--------- -57 
TRACKS-USED------ ~----57 
DATASET-DIRECTORY: 
‘DSN----PRIMER.UCATL 
DSN----CUSTOMER .K.I 
-. DSN----SALESMAN.K.I 
DATASPACE — pe ge a 
DATASETS--~------------ 2 
EXTENTS-----------~----= 1 
SEC-ALLOC-------------- 2 
TYPE------------ CYLINDER 
EXTENT-DESCRIPTOR: 
TRACKS-TOTAL-------- 1900 
TRACKS-USED-~-------- 114 


DATASET-DIRECTORY: 
DSN----CUSTOMER.K.D 
DSN----SALESMAN.K.D 


PHYREC-SIZE~-------~-512 
PHYRECS/TRK---~------- 20 
TRACKS/CA-~------~---- 19 
LOW-RBA------~----- 10240 
HIGH-RBA---------~--10751 
CREATION---------- 77.355 
EXPIRATION-------- 00.000 
RACF---------------- (NO) 
RCVY-VOL----------WTVSAM RCVY-DEVT-~--X'30502009' RCVY-CI-------- X'000009' 
DEVTYPE------X'30502009' MAX-PHYREC-SZ------ 13030 DATASETS-ON-VOL-------- 5 
VOLUME-TIMESTAMP: MAX-EXT/ALLOC---------- 5 DATASPCS-OGN-VOL-------- 2 
X' 8BDE7F 9BAS1F 9000 ' 
FORMAT-1-DSCB: ATTRIBUTES: 
CCHHR------ X'9000000303' SUBALLOC 
TIMESTAMP EXPLICIT 
-X'8BDE7FGAFA2AB800' USERCAT 
BEG-CCHH----- X'00010000' SPACE-MAP---------~-- 39 
ATTRIBUTES--~------ (NULL) EXTENTS---------------- 3 
ATTRIBUTES--------(NULL) EXTENTS~--------------- 1 
ATTRIBUTES-------- (NULL) EXTENTS---------------- 1 
FORMAT-1-DSCB: ATTRIBUTES: 
CCHHR~~----- X'0000000304' SUBALLOC 
TIMESTAMP EXPLICIT 
X' 8BDE7F50C9DD7800' | 
BEG-CCHH--~--X'00040000' SPACE-MAP----------- 72FDO6FA 
ATTRIBUTES-------- (NULL) EXTENTS--------- ------- 1 
_ ATTRIBUTES-------- (NULL) EXTENTS---------------- 1 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX --------- 


HI-ALLOC-RBA-----~- 10752 EXTENT-NUMBER---~------ 1 
HI-USED-RBA-------- 10752 EXTENT-TYPE-------- X'80! 
TRACKS---------------- 19 

RCVY-VOL---------- WTVSAM RCVY-CI-------- X'000014' 


RCVY-DEVT----X'30502009' 
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CLUSTER -~-------------- 2 
DATA ~----------------- 3 
GDG -~~~----~--=+--=---- 0 (*) 
INDEX ~-~--------------- 3 
NONVSAM ~--------------- 0 
PAGESPACE ~<-<----<------- O () 
PATH ------~------------ l 
SPACE --~---------~----- 1 
USERCATALOG ----------- 0 
TOTAL --------<-<------- ll 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


(*) = these lines do not apply to DOS/VS. 


7.9.2.1 EXTRACTING ALL ALLOCATIONS FROM LISTCAT ALL 


The following information containing the allocation values of all 
components on the volume WTVSAM has been extracted from the previ- 
ous list. The entries have been sorted to show the sequence of 
allocating space (see figure 41 in next section on page 151). 


1. User catalog data component: 


The first extent describes the Low-Keyrange and the second the 
High-Keyrange (the index allocation is between). 


CLUSTER ~------- PRIMER .UCAT1 
DATA ------- VSAM.CATALOG.BASE .DATA.RECORD 

VOLUME 
EXTENTS: 
LOW-CCHH--~--- X'00010000' LOW-RBA---~------------- 0 TRACKS 344 ss oeSeesese 30 
HIGH-CCHH----X'0002000A' HIGH-RBA---------- 204799 

VOLUME 
EXTENTS: 
LOW-CCHH~---- X'O0002000E' LON-RBA--~--------- 204800 TRACKS-~---------- Sanne 3 


HIGH-CCHH----X'00020010' HIGH-RBA---~-----~-- 225279 
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2. User catalog Index component: 


CLUSTER ---~---- PRIMER.UCAT1 
INDEX ------ VSAM. CATALOG.BASE.INDEX.RECORD 
VOLUME 
EXTENTS: 
LOW-CCHH-~--~-- X'0002000B' LOW-RBA---------------- 0 TRACKS<----------------- 3 
HIGH-CCHH----X'0002000D' HIGH-RBA----------- 30719 


Note: The second and third volume entry of the index component 
repeat the data component entries, since the Index Sequence Set 
records are stored with the data (IMBED). 


3. Cluster CUSTOMER.K Index component 


The cluster was defined with IMBED. This is the Index Set. The 
Index Sequence Set is stored with the data component. 


CLUSTER ------- CUSTOMER .K 
INDEX ------ CUSTOMER .K.I 
VOLUME 
EXTENTS: 
LOW-CCHH----- X'00030011' LOW-RBA---------------- 0 TRACKS <<<-3=-<9"=<e5--- - 
HIGH~CCHH-~--X'00030011' HIGH-RBA----------- 12287 


Note: The second and third volume entry of the index component 
repeat the data component entries, since the Index Sequence Set 
records are stored with the data (IMBED). 


u. Alternate index SALESMAN.K Index component: 


The alternate index was defined with IMBED (see description above! 


AIX e---------- SALESMAN .K 
ENDEX: --==== SALESMAN.K.I 
VOLUME 
EXTENTS: 
LOW-CCHH---~-- %'00030012' LOW-RBA--~----~---------- OC TRACKS==<==-S<5==-=<se= 1 
HIGH-CCHH----X'00030012' HIGH-RBA----------- 10239 


Note: The second and third volume entry of the index component 
repeat the data component entries, since the Index Sequence Set 
records are stored with the data (IMBED). | 
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5. Cluster CUSTOMER.K Data component 


CLUSTER ------- CUSTOMER .K 


DATA ------- CUSTOMER.K.D- 
VOLUME 
EXTENTS: | | 
_ LOW-CCHH----- X'00040000' LOW-RBA---------------- 0 TRACKS---------~------- 


6. Alternate index SALESMAN .K Data component: 


AIX ----------- SALESMAN.K 
DATA ------- SALESMAN.K.D 
VOLUME 
EXTENTS: | 
LOW-CCHH-----X'00090000' LOW-RBA---------------- 0 TRACKS---------------- 
HIGH-CCHH--~-X'00090012' HIGH-RBA-~--------- 221183 
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eee 


7.9.2.2 ALLOCATION LAYOUT ON THE VSAM 3330 VOLUME 


See description in section 7.9.2.1 on page 148 


Allocation 
(hex) CC HH 


00 00-00 12 19 tracks 


01 00-02 OA User Catalog Data (LKR) 30 tracks 


02 OB-02 OD User Catalog Index 3 tracks Data space 
3 allocated 
02 OE-02 10 User Catalog Data CHKR) 3 tracks With DEFINE 


USERCATALOG 
a a: - 


03 11 CUSTOMER. K Index 1 track 
03 12 AIX SALESMAN.K Index 1 track 


04 00-08 12 CUSTOMER.K Data 95 tracks 
| Data space 
allocated 
with 
DEFINE SPACE 


09 00-09 12 AIX SALESMAN.K Data 19 tracks 


Figure 41. Volume allocation layout 
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7.9.2.3 EXPLANATION OF THE LISTCAT OUTPUT FIELDS: 


Cluster entry = 


CLUSTER ------- - CUSTOMER .K 

HISTORY 3 
OWNER-IDENT------- (NULL) CREATION---------- 77.355 RCVY-VOL---------- WTVSAM RCVY-CI-------- X*00000E' 
RELEASE--------~------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X' 30502009! 

PROTECTION-PSKD----- (NULL) RACF----------------(NO) | 

ASSOCIATIONS 
DATA----- CUSTOMER.K.D 
INDEX-~--CUSTOMER.K.I 
AIX------ SALESMAN.K 


Explanation: 


OWNER-IDENT: 1 to 8 characters that can be specified for DEFINE 
CLUSTER. Used to identify the OWNER Cowner-id) of the 
object. "(NULL)" means no owner-id was specified. 


CREATION: the julian date (YY.DDD) the entry was created. 


EXPIRATION: the cluster can be deleted without specifying the PURGE 
parameter (00.000). 


RCVY-VOL: the volume serial where the CRA containing duplicated 
catalog records for this object is located 


RCVY-CIL: the CI number in the CRA which contains the duplicated 
catalog entry for this cluster. X'OE' means CI number 
14. 


RELEASE: Release number of VSAM under which the entry was created 
(the format of catalog records may change between releas-— 
es, however, externals for the user are maintained). 


DOS/VS: 1 = DOS/VS Rel. 28, 29, and 30 
2 = DOS/VS Rel. 31 and up 
OS/MVS: 1 = OS/VS2 Rel. 2 and 3 
2 = OS/VS2 Rel. 3.6 and up 
OS/SVS: 1 = SVS without VSAM ICR 
| 2 = SVS with VSAM ICR 
OS/7VS1: 1 = OS/ZVS1 incl. Rel. 3.0 
2 OS/VS1 Rel 4.0 and up 


RECY-DEVT: device type of the volume containing the CRA for this 
object. A translate table is included in the Access 
Method Services manual and in section C.1 on page 279. 
X'30502009' means 3330. 


The explanations are continued on the next page. 
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PROTECTION-PSWD: indicates the MASTERPW, CONTROLPW, UPDATEPW and/or 
READPW for this object. ‘'(NULL)" means no password has 
been specified. 


RACF: (this heading appears in MVS. only) "(NO)" means this 
entry is not RACF protected. 


ASSOCIATIONS: this group lists the types and entry names of each 
entry associated with the present entry. This object 
(cluster) is associated with its data and index objects 
and also with an alternate index (AIX) cluster. 


Cluster data component entry 


HISTORY 
OWNER-IDENT-~------~ (NULL) CREATION---------- 77.355 RCVY-VOL---~------- WTVSAM RCVY-CI--~------ X'00000D' 
RELEASE=-=-s<<se--s--+< 2 EXPIRATION-------- 00.000 RCVY-DEVT-~---X'30502009' 

PROTECTION-PSKD----- (NULL) RACF-----~----------- (NO) 

ASSOCIATIONS 
CLUSTER~--CUSTOMER .K 

ATTRIBUTES 
KEY LEN===-=-=-=<-+=-=-- 5 AVGLRECL-----~------- 200 BUFSPACE------------ 4096 CISIZE=<=~=-------+- 1024 
RKP +Ss=2S2seeSeoeesoere 0 MAXLRECL~------------- 200 EXCPEXIT---------- (NULL) CI/CA+--=-==25--==5-=- 198 
SHROPTNS(1, 3) RECOVERY SUBALLOC NOERASE INDEXED NOWRITECHK IMBED NOREPLICAT 
UNORDERED NOREUSE NONSPANNED 


Explanation: 


For explanation of HISTORY, PROTECTION and ASSOCIATIONS see previ- 
ous section. 


Note that 3850 (MSS) default parameters NODESTAGEWAIT and STAGE are 
not listed with LISTCAT. 


KEYLEN: length of primary Key (5 bytes). 


RKP: relative key position in the logical record (key starts 
With Byte 0). 


AVGLRECL: logical record length average is 200 bytes. 


MAXLRECL: maximum record length is 200 bytes. 


The explanations are continued on the next page 
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BUFSPACE: 


minimum space. in bytes that will be used by VSAM £or data. 


and index buffers for this KSDS cluster. This value was 


defaulted by VSAM as no parameter was specified. It can 
be specified with the DEFINE command or changed with the 


ALTER command. It can also he temporarily overridden by 


CISIZE: 
CI/CA: 
EXCPEXIT: 


SHROPTNS: 


RECOVERY: 


SUBALLOC: 
NOERASE: 
INDEXED: 
NOWRITECHE 
IMBED: 


NOREPLICAT: 
UNORDERED: 


NOREUSE: 


NONSPANNED : 


a user program at OPEN time either by specifying a 
greater value in the ACB (see chapter 8.11 starting on 
page 217) or in ‘the JCL (see EEE Opes e te. section in 
chapter 6.0). _* > . - | 


conyTot interval size for this data component in bytes. 
number o€ Sentestanteeucie.- pee control area. 


"C(NULL)' means no exception exit routine entry was 
Spe ee ene in the DEFINE command . an a 


the SHAREOPTIONS were defaulted to: 173 (see section 7.2.7 


on page 95). 


is a loading option (see description in section 7.2.8 on 
page 97. a te xB 
The opposite attribute is SPEED which gives better 
performance when loading the data set, but does not. 
provide the RECOVERY facilities (also see section 7.2.8 
on page 97). a | | ee 


the space Poe this cluster is suballocated a VSAM from a 
suballocatable data BPaces 


the data are not Pere with /X'00' when the entry is 
deleted. - 4 | 7 | 


INDEXED identifies this cluster as KSDS. 


CK: write operations are noe: “eneehed for correctness. 
Specification of WRITECHECK results in time consuming 
operations not needed for DASDs like 3330, 3340, or 3350. 


the sequence- set index record is stored along with ieee 
data control area ane is emi ot on its track. 

the index records on. ‘the higher ales level er 
wept (NOREPLICAT) (also see section 7.2.3 on page 
89). .o*, | | 
‘this is a meaningless default parameter as only on 
volume is used. Tf more volumes are used, it specifies 


the order of using the volumes for allocation. 


this data set senhoe be used as. temporary work data set. 
This parameter cannot be. changed with. ALTER. 


the records guano e: span control. intervals. 
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; Cluster data component entry (statistics) . 


STATISTICS 
REC-TOTAL----~------- 3000 SPLITS-CI---------~----- 0 EXCPS--------------- 1601 
REC-DELETED------~------ 0 SPLITS-CA~------------- 0 EXTENTS$<--------------- 1 
REC-INSERTED----------- 0 FREESPACE-/CI--------- 20 SYSTEM-TIMESTAMP: 
REC-UPDATED------------ 0 FREESPACE-“~CA---~------ 10 X'8BDE7F92DF1F7800' 
REC-RETRIEVED---~---- 3010 FREESPC-BYTES----- 245760 


Explanation: 


REC-TOTAL: this data component contains 3000 records. 


REC-DELETED: no records have been deleted since the data set was 
loaded. 


REC-INSERTED: no records have been inserted after loading the data 
set (records added at the end are not counted here, 
therefore this field will always be '0' for an ESDS). 


REC-UPDATED: no records have been updated in the data set. gore 
field is updated when a PUT UPDATE request is issued ior 
a record. | | 


REC-RETRIEVED: 3010 records have been read (3000 by BLDINDEX (Cpage 
113) when the alternate index was created and 10 by PRINT 
(page 109 and page 115)). . 


SPLITS CI/CA: number of CI and CA splits since the data set was 


loaded. The "SPLIT CA‘ field should be examined 
frequently. If the value increases too much, the data 


set should be reorganized. 


FREESPACE-AZCI/CA: 20% free space in the CI (1024 * 20% = 204 bytes) 
and 10% of the number of CI per CA (198 * 10% = 19 CI) 
are left free when the data set is loaded (also see 
section 7.2.2 on page 88). 


FREESPC-BYTES: this is the amount of free bytes in the data compo- 
| nent, excluding the free space in the partially filled 
CI's. This value can be calculated as follows: 


1. records per CI (minus free space) = 4 

2. CI required (3000 red 7 4 ) = 750 

3. tot. alloc. CIs(198 (CI/CA) * 5 (CAF=cyl1l)) = 990 

4. free CIs (990 - 750 = 240) * 1024 bytes = 245760 
EXCPS: 1601 EXCP (execute channel program ~—- SVC 0} macro 


instructions have been issued against this data component 
Cabout 50% when loading the data set, the rest by BLDIN- 
DEX and PRINT). 


The explanations are continued on the next page 
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EXTENTS: the number of extents of this data component. 
SYSTEM-TIMESTAMP: the time (System/370 time-of-day clock value) 


this data component was last closed (no important times- 
tamp). : | 


: Cluster data component entry Callocation) 


ALLOCATION 
SPACE-TYPE------ CYLINDER HI-ALLOC-RBA---~--- 1013760 
SPACE -PRI-~~-----~------ 5 HI-USED-RBA--~--- 1013760 


SPACE-SEC-------------- 2 
Explanation: 


SPACE-TYPE: indicates whether the suballocation of this data 
component is in terms of CYLINDERS or TRACKs. 


SPACE-PRI: contains the number of units: indicated by SPACE-TYPE of 
space allocated to this data component when it was 
defined (the same amount would be allocated ona new 
CANDIDATE volume if the data component space must _ be 
extended. 


SPACE-SEC: contains the number of units indicated by SPACE-TYPE of 
space to be allocated whenever the data component is tc 
be extended on the same volume. 


HI-ALLOC-RBA: the highest RBA (plus 1) allocated by VSAM for this 


data component to store data. The calculation is as 
follows: : 


990 (CIs) * 1024 Cbhytes/CI) = 1 013 760 bytes 
HI-USED-RBA: the highest RBA (plus 1) within allocated space that 


actually contains data. Since the data set was loaded 
With the RECOVERY option, the last CA is always prefor- 


matted. Actually it does not contain records at the end 
but some FREESPC-BYTES for extending/adding more data 
records. 
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Cluster data component entry (volume information) 


VOLUME 
VOLSER------------ WTVSAM PHYREC-SIZE--------- 1024 HI-ALLOC-RBA----- 1013760 EXTENT-NUMBER---------- 
DEVTYPE------ X'30502009' PHYRECS/TRK----------- 11 HI-USED-RBA------ 1013760 EXTENT-TYPE-------- X'00' 
VOLFLAG------------ PRIME TRACKS/CA------------- 19 
EXTENTS: 
LOW-CCHH----- X'00040000' LOW-RBA---------------- 0 TRACKS---------------- 95 


HIGH-CCHH----X'00080012' HIGH-RBA--~------- 1013759 


Explanation: 
VOLSER: the volume serial number WTVSAM. 


DEVTYPE: the device type is 3330 (the Access Method Services 
Manual contains a ‘Device Type Translate Table' to 
translate this code, also see section C.1 on page 279). 


VOLFLAG: PRIME indicates that this is the first volume on which 
data records for this data component are stored. Other 
values may indicate OVERFLOW when the component contains 
a Keyrange, or CANDIDATE where the component can be 
extended. 


PHYREC-SIZE: physical record size (sometimes called block size) 
that VSAM uses to write CIs for this data component on 
this device type (also see section 8.2, page 196). 


PHYSRECS/TRK: 11 physical records with 1024 #=bytes (no Key) are 
written per track on a 3330. 


TRACKS/CA: one CA is 19 tracks. Since the allocation was made in 
terms of CYLINDERS, VSAM set the CA size equal to one 
cylinder. One cylinder on a 3330 contains 19 tracks. 


HI-ALLOC-RBA: see previous page (allocation). 
HI-USED-RBA : see previous page (allocation). 


EXTENT-~NUMBER: number of extents allocated for this data component 
on volume WTVSAM. 


EXTENT-TYPE: X'00° means the extents are contiguous. 
X'4HO' means the extents are not preformatted. 


X'80' is only used in an index component. As the volume 
“group for the data component is repeated in an iicex 
component when IMBED is specified, xX‘'80' indicates that 


the sequence set occupies the first track of the data CA. 
LOW/HIGH-RBA: the RBA indicating the begin/end of this extent. 


TRACKS: 95 tracks (5 cylinders) are allocated for this extent. 
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- INDEX ------ CUSTOMER .K.I 


HISTORY 
OWNER-IDENT-~-~----- (NULL) CREATION--~-~-~---~-- 77.355 RCVY-VOL---------- WIVSAM RCVY-CI-------- X'OOO00F' 
RE LEASE ~-<--- +--+ -—-~~~= 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30502009' 

PROTECTION-PSWD----- (NULL) RACF------------ ----(NO) | 

ASSOCIATIONS 
CLUSTER-~-CUSTONER .K 

ATTRIBUTES 
KEV LENS =2ssHS+< sees =s 5 AVGLRECL-<-- eee - eee 0 BUFSPACE==-24-sSeee eee > 0 CIVIL ZG Heese ee Sess= £048 
RR Pawnee newer ween enna MAXLREC Lene nnn ne 2041 EXCPEXIT~--------- CNULLD CL/CAtescn sess ese eS See 
SHROPTNS(1; 3) RECOVERY SUBALLOC NOERASE NOWRITECHK IMBED NOREPLICAT UNORDERED 
NOREUSE 

STATISTICS 
REC-TOTAL~--~------------ 6 SPLITS-CI-------------- 0 EXCP§----- <2 - ee - ee eo ee 48 INDEX: 
REC-DELETED---<<--+>-+<== 0 SPLITS-CA-~~~-~-+-------- 0 EXTENT S=<45<=5=2=s-3Se5 @ GEVELSesoeseeeeeesoese= 
REC-INSERTED----------- 0 FREESPACE-ZCI---------- 0 SYSTEM-TIMESTAMP: ENTRIES/SECT--~-------- 14 
REC-UPDATED------~----- 0 FREESPACE-/CA---------- 0 X'8BDE7F92DF1F7800' SEQ-SET-RBA-------- 12288 


REC~RETRIEVED------ ----0 FREESPC-BYTES------ 10240 HI-LEVEL-RBA----------- 


Explanation: 


Almost every parameter was explained in the previous sections. 


The only new and/or important parameters here are: 


INDEX LEVELS: '2° specifies that 2 index levels are built. The 
first level is the 'Sequence set level’ which is stored 
With the data component CIMBED). The second level is the 
‘Index set level'. 


REC-TOTAL: '6’ means a total of 6 index records (CIs) exist. The 
sequence set consists of 5 index records (one per CA) and 
the index set consists of one index record (with the five 

entries pointing to the sequence set records). 
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Catalog volume record (with volume timestamp) 


VOLUME -------- WTVSAM 
HISTORY 
RELEASE -~-----+--------- 2 RCVY-VOL----------~ WTVSAM RCVY-DEVT--~--X'30502009' RCVY-CI--~------ X'000009° 
CHARACTERISTICS 
BYTES/TRK---------- 13165 DEVTYPE------ X%'30502009' MAX-PHYREC-SZ------ 13030 DATASETS-ON-VOL-------- 5 
TRKS/CYL-------------~ 19 VOLUME-TIMESTAMP: MAX-EXT/ALLOC---------- 5 DATASPCS-ON-VOL---~----- 2 
CYLS/VOL-----~-------- 411 X' 8BDE7F 9BA51F9000' 


Explanation: 


BYTES/TRK: specifies the maximum bytes per track (not all usable by 
VSAM). : 
TRKS/CYL: this device type (3330) has 19 tracks per cylinder. 
CYL/VOL: this device type (3330) has 411 cylinder per volume. 
DEVTYPE: this is a 3330 (see explanation in previous section). 
MAX-PHYREC-SZ: the theoretical maximum physical record size VSAM. 


can write on this volume Sizes in 


(see physical record 
section 8.2 on page 196). | 
LOC: the maximum number of extents per allocation 
request. This means if a primary or secondary allocation 
request for a suballocated data set (in OS/VS also for an 
UNIQUE data set) is issued, for example, for 10 cylin- 


MAA-EAT/AL 


ders, VSAM Cor in OS/VS for an UNIQUE data set OS/DADSM) 

tries to allocate these 10 cylinders ina maximum of 5 

pieces. | 
DATASETS-ON-VOL: there are 5 logical data sets stored on the 

volume: : 

1. Catalog - CLUSTER. 

2. KSDS - DATA 

3. KSDS - INDEX 

uy AIX ~ DATA 

5. AIX - INDEX 


DATASPCS-ON-VOL: there are 2 data spaces on the volume (one created 
With DEFINE USERCATALOG, and one created with DEFINE 
SPACE). 


VOLUME-~TIMESTAMP: this is the most and only important timestamp in 


VSAM. This timestamp is checked by VSAM against the 
timestamp in the VTOC F-4Y DSCB timestamp. 
The timestamp is described in detail in section A.2 on 
page 244, 
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7.190 LISTCRA 


7.10.1 LISTCRA NOCOMPARE 


DOS/VS example (input): 


//7 JOB LIST CRA NO COMPARE 
7/7 BDLBL WTVSAM;> »»,VSAM 
77 EXTENT SYS010,WTVSAM 
7/7 ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
77 EXEC IDCAMS, SIZE=AUTO 
LISTCRA INFILE (WTVSAM) - 
NOCOMPARE NAME = 
MASTERPW (MCATMRPH) - 
CAT (PRIMER.UCATI/UCATMPRW WTVSAM) 
7% 


DOS/VS example Coutput): 


LISTING OF CRA FOR VOLUME --WTVSAM-- VSAM ENTRIES 
VOL - WTVSAM 


CRAVOLRCD - 10720/77 15:50:33 
FGDSCBVSAM - 10/20/77 15:50:33 
FG4DSCBDUMP - 10/20/77 15:50:33 


AIX - CITY.E 
DATA - CITY.E.D 
DATA VOL. - 
WTVSAM 
INDX - CITY.E.I 
INDX VOL - 
WTVSAM 
WTVSAM 
CLUS - CUSTOMER.E 
PATH - CITY.CUST.E 
AIX - CITY.K 
DATA - CITY.K.D 
DATA VOL - 
WTVSAM 
INDX - CITY.K.I 
INDX VOL - 
WTVSAM 
WTVSAM 
CLUS - CUSTOMER.K 
PATH - CITY.CUST.K 


| Output listing is continued on next page 


160 VSAM PRIMER and REFERENCE 


OS/VS example Cinput): 


//PRIMER JOB WTSC,IBM,»MSGLEVEL=1 

//PRIMO342 EXEC PGM=IDCAMS 

//WTVSAM DD VOL=SER=WTVSAM,DISP=OLD ;UNIT=3330 

//SYSPRINT DD SYSOUT=A 

//SYSIN = DD * 

LISTCRA INFILE (WTVSAM) - 

NOCOMPARE NAME - 
MASTERPW (MCATMRPW) - 
CAT (PRIMER.UCATL/UCATMPRH WTVSAM ) 

7% 


OS/VS example Coutput): 


LISTING OF CRA FOR VOLUME --WTVSAM-- VSAM ENTRIES 
VOL - WTYSAM 


CRAVOLRCD - 12/22/77 05:35:30 
FGDSCBVSAM - 12/22/77 05:35:30- 
FGDSCBDUMP - 12/22/77 05:35:30 


AIX - CITY.E 
DATA - CITY.E.D 
DATA VOL - 
WTVSAM 
INDX - CITY.E.I 
INDX VOL - 
WTVSAM 
WTVSAM 
CLUS ~- CUSTOMER.E 
PATH - CITY.CUST.E 
AIX - CITY.K 
DATA - CITY.K.D 
DATA VOL - 
WIVSAM 
INDX - CITY.K.I 
INDX VOL - 
WTVSAM 
WTVSAM 
CLUS - CUSTOMER.K 
PATH - CITY.CUST.K 


aaa 


CLUS - CUSTOMER.E 


DATA - CUSTOMER.E.D 


DATA VOL - 
WTVSAM 
AIX - SALESMAN.E 
DATA VOL - 
WTVSAM 
INDX VOL - 
WTVSAM 
WTVSAM 
AIX - CITY.E 
DATA VOL - 
WTVSAM 
INDX VOL ~ 
WT VSAM 
WIVSAM 
UPGD - 
CLUS - CUSTOMER.K 


DATA - CUSTOMER.K.D 


DATA VOL - 
WTVSAM 


INDX - CUSTOMER.K.I 


INDX VOL - 
WIVSAM 
WTVSAM 

AIX - SALESMAN.K 

DATA VOL - 
WTVSAM 

INDX VOL - 
WIVSAM 
WTVSAM 

AIX - CITY.K 

DATA VOL - 
WTVSAM 

INDX VOL - 
WTVSAM 
WTVSAM 

UPGD - 
CLUS - CUSTOMER.R 


DATA - CUSTOMER.R.D 


DATA VOL - 
WT VSAM 
AIX - SALESMAN.E 


DATA - SALESMAN.E.D 


DATA VOL - 
WTVSAM 


INDX - SALESMAN.E.I 


INDX VOL - 
WTVSAM 
WTVSAM 

CLUS - CUSTOMER.E 


PATH ~- SALES.CUST.E 


CLUS - CUSTOMER.E 
DATA - CUSTOMER.E.D 


DATA VOL - 
WIVSAM 
AIX - SALESMAN.E 
DATA VOL - 
WTVSAM 
INDX VOL - 
WTVSAM 
WTVSAM 
AIX - CITY.E 
DATA VOL ~ 
WTVSAM 
INDX VOL - 
WTVSAM 
WTVSAM 
UPGD - 


CLUS - CUSTOMER .K 


DATA ~- CUSTOMER.K.D 
DATA VOL - 
WTVSAM 
INDX - CUSTOMER.K.I 
INDX VOL - 
WTVSAM 
WTVSAM 
AIX - SALESMAN.K 
DATA VOL - 
WTVSAM 
INDX VOL - 
WIVSAM 
WT VSAM 
AIX - CITY.K 
DATA VOL - 
WTVSAM 
INDX VOL - 
WTVSAM 
WTVSAM 
UPGD - 


CLUS - CUSTOMER.R 


DATA - CUSTOMER.R.D 
DATA VOL - 
WTVSAM 


AIX - SALESMAN.E 


BATA - SALESMAN.E.D 
DATA VOL - 
WTVSAM 
INDX - SALESMAN.E.I 
INDX VOL - 
WTVSAM 
WTVSAM 
CLUS - CUSTOMER.E 
PATH - SALES.CUST.E 


OCutput listing is continued on next page 
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AIX - SALESMAN.K 
DATA - SALESMAN.K.D 
DATA VOL - 
WTVSAM 
INDX - SALESMAN.K.I 
INDX VOL - 
WTVSAM 
WTVSAM 
CLUS ~- CUSTOMER.K 
PATH - SALES.CUST.K 
NUMBER OF ENTRIES PROCESSED 


CLUS - 
DATA - 
AIX -~ 
INDX ~ 
PATH - 
VOL - 
UPGD - 
SUM - 


3 


ne ff UD SI 


26 


AIX - SALESMAN.K 
DATA - SALESMAN.K.D 
DATA VOL - 


INDX - SALESNMAN.K.I 
INOX VOL - 


CLUS ~- CUSTOMER.K 


WT VSAM 


WTVSAM 
WTVSAM 


PATH ~- SALES.CUST.K | 
NUMBER OF ENTRIES PROCESSED 


CLUS 
DATA 
AIX 

—INDX 
PATH 
VOL 
UPGD 
SUM 


3 


ne PU Lf NY 


26 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCQO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: . 


° The master password of the 
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master catalog 
specified if the master catalog is password 


(MASTERPW) must be 
protected. 


7.10.2 


// JOB LIST CRA COMPARE 
77 DLBL WTVSAM; » »VSAM 
7/7 EXTENT SYSO10,WTVSAM 
// ASSGN SYS010,DISK, VOL=WTVSAM, SHR 
/7 EXEC IDCAMS, SIZE=AUTO 
LISTCRA INFILE (WTVSAM) = 


/& 


LISTING OF CRA FOR VOLUME --WTVSAM-- VSAM ENTRIES 


LISTCRA COMPARE 


DOS/VS example (input): OS/VS example Cinput): 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//7PRIMO352 EXEC PGM=IDCAMS 
//STEPCAT DD DSN=PRIMER.UCAT1,DISP=OLD 
//WTVSAM DD: VOL=SER=WTVSAM, DISP=OLD , UNIT=3330 
//CATVOL DD DSN=PRIMER.UCAT1,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
LISTCRA INFILE (WTVSAM) - 
COMPARE NAME - 
MASTERPW (MCATMRPH) - 
CAT (PRIMER.UCAT1/UCATMRPHW CATVOL) 


COMPARE NAME - 
CAT (PRIMER.UCATL/UCATMRPW IJSYSUC)- 
MASTERPW (MCATMRPW) 


7*® 


DOS/VS example (output): OS/VS example (output): 


LISTING CRA FOR VOLUME --WTVSAM-- VSAM ENTRIES 


CATVOLRCD - 10/20/77 15:50:33 CATVOLRCD - 12/22/77 05:35:30 
CRAVOLRCD - 10/20/77 15:50:33 CRAVOLRCD - 12/22/77 05:35:30 
F4DSCBVSAM - 10/20/77 15:50:33 FGDSCBVSAM - 12/22/77 05:35:30 
F4DSCBDUMP - 10/20/77 15:50:33 FG4DSCBDUMP - 12/22/77 05:35:30 
NUMBER OF ENTRIES PROCESSED NUMBER ENTRIES PROCESSED 
CLUS - 3 CLUS - 3 
DATA - 7 DATA - 7 
AIX - 4 AIX - 4 
INDX - 5 INDX - 5 
PATH - q PATH - 4 
VOL - 1 VOL - 1 
UPGD - 2 UPGD - 2 
SUM - 26 SUM - 26 


IDCO665I NUMBER ENTRIES MISCOMP. IN THIS CRA - 0 
IDCO877I NUMBER RECORDS MISCOMP. IN THIS CRA - 0 | 


IDCO665I NUMBER ENTRIES MISCOMP. IN THIS CRA - @ 
IDC0877I NUMBER RECORDS MISCOMP. IN THIS CRA - 0 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMNS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


LISTCRA with the COMPARE option can be used to detect the 
following conditions for a recoverable catalog: 


_ data set not properly closed 
- inaccessible data set 
= inaccessible volume 


the catalog and the CRA are 
degree of seriousness, differ- 
suggested in the 


The mismatches detected between 
listed. Then, depending on the | 
ent procedures to recover are to be taken as 
appropriate Access Method Services manual. 
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7.11 RESETCAT 
DOS/VS example Cinput): | OS/VS example Cinput): | 
// JOB RESET USER CAT : //PRIMER JOB WTSC,IBM,MSGLEVEL=1 | 
//7 DLBL WTVSAM, »,VSAM | — Z7PRIMO362 EXEC PGM=IDCAMS 
7? EXTENT SYSO10,WTVSAM © //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
7/7 ASSGN SYSO10,DISK,VOL=WTVSAM, SHR // DD DSN=PRIMER.UCAT2 ,DISP=OLD 
7/7 OLBL IJSYSWC, ‘PRIMER .UCAT2' »99/365,VSAM //UCATDD DD DSN=PRIMER.UCATL,DISP=SHR 
// EXTENT SYSO20,WTVSIR //WTVSAM DD VOL=SER=WTVSAM,UNIT=3330 ,DISP=OLD 
//7 OLBL IDCUT1, »,VSAM,CAT=IJSYSWC | /7WORKF DD DSN=WORKFILE ,DISP=OLD ,UNIT=3330, 
// EXTENT SYS020,WTVSIR 1/7 VOL=SER=WTVS1R ,AMP=' AMORG' 
//7 ASSGN SYS020,DISK,VOL=WTVS1R SHR //SYSPRINT DD SYSOUT=A 
7/7 EXEC IDCAMS,SIZE=AUTO | //SYSIN DD x 
RESETCAT CAT (PRIMER.UCATI/UCATMRPW IJSYSUC)- RESETCAT CAT(PRIMER.UCATL/UCATMRPW UCATDD )- 
CRAFILES (WTVSAM ALL) — - CRAFILES ((WTVSAM ALL)) - 
WORKCAT (PRIMER.UCAT2 IJSYSWC)- _ WORKCAT (PRIMER.UCAT2) - 
MASTERPW (MCATMRPW) - MASTERPW (MCATMRPW) - 
NOIGNORE WORKFILE (WORKF) 
7% | [* | 
DOS/VS example Coutput): OS/VS example Coutput): 
IDCO1LOO0ZI RESETCAT CATALOG PRIMER.UCATL IDCO1LO02I RESETCAT CATALOG PRIMER.UCAT1 
VOL WTVSAM LEVEL 10/20/77 16:24:15 VOL WTVSAM LEVEL 12/22/77 05:35:30 
IDCO1O11I CRA FOR RST-VOL WTVSAM | IDCO1011I CRA FOR RST-VOL WTVSAM - 
LEVEL 10/20/77 16:24:15 LEVEL 12/22/77 05:35:30 
IDC01037I PRIMER.UCAT1 HAS BEEN RESET IDC01037I PRIMER.UCAT1 HAS BEEN RESET 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 rpcoo02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


RESETCAT must be used with caution to recover accessibility of 
a volume that contains a portion of a multivolume file. Prior 


to issuing RESETCAT, compatible levels of volumes containin; 


multivolume ‘files should be restored. Refer to the Access 
Method Services manual for more information. 


RESETCAT function requires a WORKFILE for use as temporary 
storage while processing the command. The space required is 
suballocated from VSAM space(s) on the volume specified in its 
EXTENT statement. Be sure the available suballocatable space 


on the WORKFILE volume is at least as large as the resultant 
catalog. | 


The master password of the master catalog (MASTERPW) must be 
specified if the master catalog is password protected. 


The WORKCAT catalog will be used to define this WORKFILE (Cand 


to delete it at the end) since the catalog being reset can not 
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be used during such operation. Any other catalog can be used. 
It must be connected to the master catalog. 


The notes are continued on the next page. 


VSAM PRIMER and REFERENCE 


fo 


DOSZ 


VS notes: 


The WORKFILE's DLBL/EXTENT must specify the 'dname' CIDCUT!1 1s 
the default name in case the parameter WORKFILE (dname) is not 
specified), the ‘'volid' where the WORKFILE will be allocated 
(WIVS1R) and the CAT parameter indicating the catalog this 
volume belongs to (IJSYSWC). The DLBL/EXTENT information for 
the WORKCAT catalog must be provided. | 


7.12 EXPORT DISCONNECT USER CATALOG FROM MASTER CATALOG 
DOS/VS example Cinput): OS/VS example Cinput): 

// JOB EXPORT DISCONNECT UCAT //PRIMER JOB WTSC,IBM,MSGLEVEL=1 

// DLBL IJSYSUC, 'PRIMER.UCATL',,VSAM //PRIMO372 EXEC PGM=IDCAMS 

// EXTENT SYS010,WTVSAM,1,0,19,57 7/7SYSPRINT DD SYSOUT=A 

// ASSGN SYS010,DISK, VOL=NTVSAM, SHR //SNSIN DD * 

//7 EXEC IDCAMS,SIZE=AUTO EXPORT PRIMER.UCATL/UCATMRPW ~ 
EXPORT PRINER.UCATI/UCATMRPW ~ DISCONNECT 

DISCONNECT /* 

(& 

DOS/VS example Coutput): OS/VS example (Coutput): 


IDCOOO1LI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOOI1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCOO0O2TI IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


DOSZ 


gS ° 

EXPORT DISCONNECT is required to signal the action to discon- 
nect the user catalog PRIMER.UCAT1 (whose UPDATEPW or MASTERPW 
is required) from the master catalog. 


The user catalog volume need not to be mounted. 


VS note: 


MVS 


No DLBL/EXTENT statements are required. 
notes: 


The EXPORT DISCONNECT command removes the ALIASes for the usec 
catalog from the master catalog (the IMPORT CONNECT comme>7 


does not recatalog the ALIASes). 


Before issuing an EXPORT DISCONNECT command issue a LISTCAT 


VOLUMES command to ‘list all ALIASes. After the IMPORT CONNECT 
command, each ALIAS must be entered into the master catalog 
with a separate DEFINE ALIAS command (see example on page 183). 
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TANS 


IMPORT CONNECT A USER CATALOG TO THE MASTER CATALOG 


DOS/VS example (Cinput): OS/VS example Cinput): 
7/7 JOB IMPORT CONNECT UCAT | 7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 
7/ DLBL IJSYSUC, 'PRIMER.UCAT1', »VSAM 7/PRIMO382 EXEC PGM=IDCAMS 
7/7 EXTENT SYS010,NTVSAM;1,0519)57 //SYSPRINT DD SYSOUT=A 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR | /7SYSIN DD * : 
/7 EXEC IDCAMS,SIZE=AUTO IMPORT CONNECT | _- 
IMPORT CONNECT - OBJECTS ( a. 
| OBJECT ( - | PRIMER .UCAT1 ~ 
PRIMER .UCAT1 - DEVT (3330) ~ 
DEVT (3330) ~ | VOLUME (WTVSAM) ) ~ 
VOL (WTVSAM) ) ~ CAT (PRIMER.MCAT/MCATMRPH ) 
CAT (PRIMER .MCAT/MCATMRPH) 7% 
/& 
DOS/VS_ example Coutput): OS/VS example (Coutput): 
IDC0603I CONNECT UCAT PRIMER.UCAT1 SUCCESSFUL IDC0603I CONNECT UCAT PRIMER.UCAT1 SUCCESSFUL 


IDCOGO1LI FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 Ipco0021 IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


IMPORT CONNECT must be specified to connect (or reconnect an 
already disconnected) user catalog to the master catalog. 


A user catalog may be connected to more than one master catalog 
but should only be used from one at a time. 


A user catalog cannot be connected to another user catalog. 
OBJECT names the user catalog PRIMER.UCAT1 indicating the 
device type and volume serial number of the volume containing 


the user catalog. 


With this information, the volume containing the user catalog 


need not be mounted. 


CAT names the master catalog PRIMER.MCAT and indicates its 
UPDATEPW or MASTERPW needed for the CONNECT operation. 


DOS/VS note: 


& 
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No DLBL/EXTENT statements are required. 


VSAM PRIMER and REFERENCE 


7.14% EXPORTRA 


DOS/VS example Cinput): OS/VS_ example (input): 


//7 JOB EXPORT CRA /7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
/7 OLBL CRAVOLI,; »,VSAM //PRIMO392 EXEC PGM=IDCAMS 
/7 EXTENT SYSO010,WTVSAM /7EXPCRA ODD VOL=(,RETAIN> » »SER=057454), 
// ASSGN SYS010,DISK;,VOL=WTVSAM, SHR // UNIT=3400-6,LABEL=(5,5L); 
// TLBL SAVECRA; 'SAVE.CRA.WTVSAM' // DISP=(NEW, PASS} ,DSN=EXPCRA 
7/7 ASSGN SYS005, TAPE, VOL=057454 7/ATVSAM =: DD-—«UNIT=3330,VOL=SER=WTVSAM, 
7/7 MTC REW,SYS005 // DISP=OLD,AMP=' AMORG' | 
/7/ EXEC IDCAMS, SIZE=AUTO 7/SYSPRINT DD SYSOUT=A 
EXPORTRA CRA ((CRAVOLI ALL)) = //SYSIN DD * 


PDEV (2400)) - 7% 
) ~ 
MASTERPW (MCATMRPW) 
(& 

DOS/VS_ example Coutput): OS/VS_ example Coutput): 
IDC0669I EXPORTING FROM CRA ON VOLUME WTVSAM IDC0669I EXPORTING FROM CRA ON VOLUME WTVSAM 
IDC0670I DS EXP. IDCO670I DS EXP. | 
IDCO674I ** NAME IS CUSTOMER.R IDCO674I ** NAME IS CUSTOMER.R 
IDCO670I DS EXP. IDCO670I.DS EXP. 

IDC0674I *% NAME IS CUSTOMER.E IDCO674I ** NAME IS CUSTOMER.E 

IDCO670I DS EXP. IDC0670I DS EXP. | 

IDC0674I ** NAME IS CUSTOMER.K IDCO674I ** NAME IS CUSTOMER.K 

IDC0670I DS EXP. IDC0670I DS EXP. | 

IDCO674I ** NAME IS CITY.E IDCO674I ** NAME IS CITY.E 

IDC0670I DS EXP. IDCO670I DS EXP. 

IDCO674I ** NAME IS SALESMAN.E IDC0674I ** NAME IS SALESMAN.E 

IDC0670I DS EXP. IDC0670I DS EXP. 

IDCO674I ** NAME IS CITY.K IDCO674I ** NAME IS SALESMAN.K 

IDC0670I DS EXP. IDCO670I DS EXP. 

IDCO674I ** NAME IS SALESMAN.K IDC0674I ** NAME IS CITY.K 

IDC0676I PORT. DS CREATED ON 10/20/77 AT 16:50:1 IDC0676I PORT. DS CREATED ON 12/21/77 AT 21:38:05 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 6 IDCO001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 
IDCQ002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


OUTFILE (SAVECRA - 
ENV (BLKSZ (4096) - 


EXPORTRA CRA ((WTVSAM ALL)) = 


OUTFILE (EXPCRA) 


See notes on next page. 
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Notes: 
* A description of EXPORTRA/IMPORTRA and their functions is 
included in section A.6.3 on page 259. | 


e The master password of the master catalog (MASTERPW) must be 
specified if the master catalog is password protected. 


o. There is no option in EXPORTRA to delete the exported objects 
7 from their catalog. | 


° As with RESETCAT, special attention should be paid when working 
With multivolume files. Read carefully the explanation of 
these subparameters in the Access Method Services manual: 


ALL | INFILE | NONE , FORCE | NOFORCE 


ALL means the data sets are exported using the CRA information 
and not the catalog information. | 


° Note that the user catalog itself is not exported. 
DOS/VS notes: 


: The DLBL/EXTENT ‘for the CRA is used to point to the volume 
where the primary CRA resides. CRAVOL1 was used as a filename 
for the DLBL statement and is so coded in the EXPORTRA command. 


e The tape (SAM) device used for unloading is defined in the 
ENVironment parameter. 
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fae 


// 
// 
7 
/ 
1/ 
A 
// 
7 


LMPORTRA 


DOS/VS example Cinput): 


JOB IMPORT CRA 
DLBL CRA, 'WTVSAM', ,VSAM 
EXTENT SYSO1LO,WTVSAM 
ASSGN SYS010,DISK,VOL=WTVSAM; SHR 
TLBL SAVECRA, 'SAVE.CRA.WTVSAM' 
ASSGN SYS004, TAPE, VOL=057454% 
MTC REW,SYS004 
EXEC IDCAMS,SIZE=AUTO 
IMPORTRA INFILE (SAVECRA - 


/& 


ENV (BLKSZ (4096) - 

PDEV (2400)) ~ 

) a 

OUTFILE (CRA) ~ 
CAT (PRIMER.UCATI/UCATMRPW) 


DOS/VS example Coutput): 


IDC06041 
IDCO5501 
IDCO5501 
IDCo5201 
IDCco5081 
IOC06261 
IDCO06041 
IDCO5501 
IDCO5501 
IDCO550I1 
IDCO550I1 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO550T 
IDCO5201 


TOCO5081 


IDC06261 


DS BEING IMP. WAS EXP. 10/20/77 AT 
ENTRY (C) CUSTOMER.R DELETED 

ENTRY (D) CUSTOMER.R.D DELETED 
CATALOG RECOVERY VOLUME IS WTVSAM 
DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CUSTOMER.R 

DS BEING IMP. WAS EXP. 10/20/77 AT 16:49 
ENTRY (R) SALES.CUST.E DELETED 

ENTRY (G) SALESMAN.E DELETED 

ENTRY (D)} SALESMAN.E.D DELETED 

ENTRY €I)} SALESMAN.E.I DELETED 

ENTRY (R)} CITY.CUST.E DELETED 

ENTRY (G) CITY.E DELETED 

ENTRY (D0) CITY.E.D DELETED 

ENTRY (I) CITY.E.I DELETED 

ENTRY (C) CUSTOMER.E DELETED 

ENTRY (D) CUSTOMER.E.D DELETED 

CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CUSTOMER.E 


16:49 


OS/VS example Cinput): 


//7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

//PRIMOGO02 EXEC PGM=IDCAMS 

77STEPCAT DD DSN=PRIMER.UCAT1,DISP=OLD 

/7IMPCRA DD VOL=(,RETAIN;> »»SER=057454);, 

1/ UNIT=3400-6,LABEL=(5,SL);, 

// DISP=(OLD,PASS)},DSN=EXPCRA 

//WTDUMMY DD UNIT=3330,VOL=SER=WTVSAM,DISP=9LO, 
ff DSN=DUMMY .NAME , AMP= ‘AMORG' 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * | 


IMPORTRA INFILE (CIMPCRA) - 


/* 


OUTFILE (WTDUMMY ) = 
CAT (PRIMER.UCATI1/UCATMRPH ) 


OS/VS example (Coutput): 


IDC0604I 
IDCO5501 
IDCO5501 
IDCO5201 
IDCO5081 
IDC06261 
IDC06041 
IDCO5501 
IDCOS5501 
IDCO5501 
IDCOS5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5201 
IDCO5081 
IDC06261 


DS BEING IMP. WAS EXP. 12/21/77 AT 21:37 
ENTRY (D) CUSTOMER.R.D DELETED 

ENTRY (C) CUSTOMER.R DELETED 

CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CUSTOMER.R 

DS BEING IMP. WAS EXP. 12/21/77 AT 21:37 
ENTRY (R) SALES.CUST.E DELETED 

ENTRY (D) SALESMAN.E.D DELETED 

ENTRY (1) SALESMAN.E.I DELETED 

ENTRY (G) SALESMAN.E DELETED 

ENTRY (R) CITY.CUST.E DELETED 

ENTRY (D) CITY.E.D DELETED 

ENTRY (I) CITY.E.I DELETED 

ENTRY (G) CITY.E DELETED 

ENTRY (D)} CUSTOMER.E.D DELETED 

ENTRY (C) CUSTOMER.E DELETED 


CATALOG RECOVERY VOLUME IS WTVSAM 
DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CUSTOMER.E 
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IDC06041 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCOS5201 
IDCO5081 
IDCO5091 
IDC06261 
IDC06041 
IDCO5201 
IDCO5081 
IDCO5091 
IDC06261 
IDC06041 
IDCO5201 
IDCO5081 
IDCO5091 
IDC06261 
IDC06041 
IDCO5201 
IDCO5081 
IDCO5091 
IDCO6261 
IDC06041 
IDCO5201 
IDCO508I 
IDCO5091 
IDC06261 
IDCO0001I 


Ipcoo02r 


DS BEING IMP. WAS EXP. 10/20/77 AT 16:49 
ENTRY (R) SALES.CUST.K DELETED 

ENTRY (G) SALESMAN.K DELETED 

ENTRY (D) SALESMAN.K.D DELETED © 

ENTRY (I) SALESMAN.K.I DELETED 

ENTRY (R) CITY.CUST.K DELETED 

ENTRY (G) CITY.K DELETED 

ENTRY (D) CITY.K.D DELETED 

ENTRY (I) CITY.K.I DELETED 

ENTRY (C) CUSTOMER.K DELETED 

ENTRY (D) CUSTOMER.K.D DELETED 

ENTRY (I) CUSTOMER.K.I DELETED 

CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CUSTOMER.K 

DS BEING IMP. WAS EXP. 10/20/77 AT 16:49 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CITY.E 

DS BEING IMP. WAS EXP. 10/20/77 AT 16:49 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR SALESMAN.E 

DS BEING IMP. WAS EXP. 10/20/77 AT 16:49 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CITY.K 

DS BEING IMP. WAS EXP. 10/20/77 AT 16:50 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR SALESMAN.K 
FUNCTION COMPL.» HIGHEST COND.CODE WAS 0 


IOCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


2 A 


description of 


IDC06041 


IDCO5501 


IDCO5501 
IDCO5501 
IDCOS5S50I 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 
IDCO5501 


~Ipcos20r 


IDCO5081 
IDCO5091 
IDC06261 
IDC06041 
IDCO5201 
IDCO508I 
IDCO5091 
IDC06261 
IDC06041 
IDCO5201 
IDCO508I 
IDCO5091 
IDC0626I 
IDC0604I 
IDCO5201 
IDCO508I 
IDCO5091 
IDC0626I 
IDC06041 
IDCO5201 
IDCO5081 
IDCO5091 
IDC06261 
IDCOO0O0LI 


rocoo002r 


EXPORTRA/IMPORTRA and 


DS BEING IMP. WAS EXP. 12/21/77 AT 21:37 
ENTRY (R) SALES.CUST.K DELETED 
ENTRY (D) SALESMAN.K.D DELETED 
ENTRY (I) SALESMAN.K.I DELETED 
ENTRY (G) SALESMAN.K DELETED 
ENTRY (R) CITY.CUST.K DELETED 
ENTRY (D) CITY.K.D DELETED 
ENTRY (I) CITY.K.I DELETED 
ENTRY (G) CITY.K DELETED 

ENTRY (D) CUSTOMER.K.D DELETED 
ENTRY (I) CUSTOMER.K.I DELETED 
ENTRY (C) CUSTOMER.K DELETED 


CATALOG RECOVERY VOLUME IS WTVSAM 


DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CUSTOMER.K 

DS BEING IMP. WAS EXP. 12/21/77 AT 21:37 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR CITY.E 

DS BEING IMP. WAS EXP. 12/21/77 AT 22.32 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAM IS 0 
IMPORTRA SUCCEEDED FOR SALESMAN.E 


DS BEING IMP. WAS EXP. 12/21/77 AT 21:36 — 


CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSAN IS 0 
IMPORTRA SUCCEEDED FOR SALESMAN.K 

DS BEING IMP. WAS EXP. 12/21/77 AT 21:38 
CATALOG RECOVERY VOLUME IS WTVSAM 

DATA ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
INDEX ALLOC.STAT. FOR VOLUME WTVSANM IS 0 
IMPORTRA SUCCEEDED FOR CITY.K 

FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


their functions is 


included in section A.6.3 on page 259. 


: Et 


is not possible 


DOS/VS notes: 


e EXTENT specifies the 
VSAM 
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*yvyolid' 


objects. This 


VSAM PRIMER and REFERENCE 


to selectively 
Specifying them in the OBJECTS parameter. 


is indicated 
where CRA was chosen for the DLBL/EXTENT filename. 


restore VSAM objects 


where the IMPORTRA will import the 


in the OUTFILE parameter, 


by 


Pr 


7.16 REPRO CUNLOAD - BACKUP A USER CATALOG 


DOS/VS example (Cinput): OS/VS example (input): 
// JOB REPRO UCAT TO TAPE //PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL IJSYSUC, 'PRIMER.UCATL',,VSAM //PRIMOGL2 EXEC PGM=IDCAMS 
// EXTENT SYSO1LO»sWTVSAM) 150519557 | //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
7/7 ASSGN SYS010,DISK,VOL=NTVSAM,SHR //CATIN DD DSN=PRIMER.UCAT1,DISP=SHR 
/7 TLBL SAVUCAT, 'SAVE.UCAT' //SANEUCAT DD VOL=(,RETAIN; » »SER=057454), 
/7 ASSGN SYS005, TAPE» VOL=057454 11 UNIT=3400-6, LABEL=(6,SL), 
/7 MTC REW,SYS005 17 DISP=(NEW, PASS) ,DSN=SAVEUC, 
7/7 EXEC IDCAMS, SIZE=AUTO /f DCB=( LRECL=516,RECFM=VB,BLKSIZE=5164) 


REPRO INFILE (IJSYSUC/UCATUPDT ) 
OUTFILE (SAVUCAT 


//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 


ENV ( - ~ REPRO INFILE (CATIN/UCATMRPW )- 
BLKSZ (4096) a OUTFILE (SAVEUCAT) 
RECFM (VB) - /® 


PDEV (2400) ) - 
) 


/& 
DOS/VS example Coutput): pS OS/VS example (Coutput): 
IDCOOO05I NUMBER OF RECORDS PROCESSED WAS 413 IDCOOO5I NUMBER OF RECORDS PROCESSED WAS 422 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


° The READPW, UPDATEPW or MASTERPW of the REPROduced object must 
be specified. In this case it is the UPDATEPW. 


° Read also section A.5.1 on page 254. 


DOS/VS notes: 


e Access Method Services needs complete specifications of any 
nonvVSAM data set. | 


e IJSYSUC was the name chosen for the DLBL/EXTENT filename to 
address the object to be copied as PRIMER.UCAT1 (file-ID) on 
volume WIVSAM at SyYS010. | 
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DOS/VS example Cinput): OS/VS example (input): 


7/7 JOB REPRO UCAT FROM TAPE hy //7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

7/ DLBL IJSYSUC, 'PRIMER.UCAT1'»»VSAM bt //7PRIMOG22 EXEC PGM=IDCAMS 

77 EXTENT SYSO10,WTVSAM,1,0,19,57 | | /7STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 

//7 ASSGN SYS010,DISK,VOL=WTVSAM, SHR //SAVEUCAT DD VOL=(,RETAIN; » »SER=057454), 

/7 TLBL SAVUCAT, 'SAVE.UCAT' // UNIT=3400-6, LABEL=(6,SL), 

//7 ASSGN SYS004, TAPE» VOL=057454 C7 DISP=(OLD, PASS) ,DSN=SAVEUC, 

/7 MTC REW,SYS004 | : FF DCB=( LRECL=516 ,RECFM=VB,BLKSIZE=5164 ) 

7/7 EXEC IDCAMS, SIZE=AUTO 7 //CATOUT DD DSN=PRIMER.UCAT1,DISP=SHR 

REPRO INFILE (SAVUCAT 7 /7SYSPRINT DD SYSOUT=A 
ENV ( a /78YSIN DD * | 

BLKSZ (4096) ~ REPRO INFILE (SAVEUCAT) - 
PDEV (2400) - | OUTFILE (CATOUT/UCATMRPW) 
RECFM (VB) ) 7 /* | 


) = 
OUTFILE (IJSYSUC/UCATUPDT ) 


/& 

DOS/VS example (Coutput): OS/VS example (Coutput): 
IDCO571I CATALOG RELOAD HAS BEEN INVOKED IDCOS71I CATALOG RELOAD HAS BEEN INVOKED 
IDCOOOSI NUMBER OF RECORDS PROCESSED WAS 413 IDCOOOSI NUMBER OF RECORDS PROCESSED WAS 422 


TOCOO01T FUNCTION COMPL.» HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


DOS/VS notes: 


° Access Method Services needs complete specifications of any { 
nonVSAM data set. 


e The same consideration as in REPRO UNLOAD on page 171 applies. 
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7.18 DELETE 
7.18.1 DELETE ATX 


DELETE just one AIX and its related path(s). 


DOS/VS example (Cinput): 


/7 JOB DEL AIX SALESMAN-CUSTOMER.K ON KSDS 

//7 DLBL AIXK1, 'SALESMAN.K',,VSAM 

// EXTENT SYS010,WTVSAM 

/7 ASSGN SYS010,DISK, VOL=WTVSAM; SHR 

/7 EXEC IDCAMS,SIZE=AUTO 

DELETE SALESMAN .K - 
ALTERNATEINDEX = 
FILE CAIXK1) = 
CAT (PRIMER .UCATI/UCATMRPW ) 
7& 


DOS/VS example (Coutput): 


IDCO550I ENTRY (R) SALES.CUST.K DELETED 
IDCO550I ENTRY (G) SALESMAN.K DELETED 

IDCO550I ENTRY (D) SALESMAN.K.D DELETED 
IDCO550I ENTRY (I) SALESMAN.K.I DELETED 


//PRIMER 


OS/VS example (input): 


JOB WTSC,IBM,MSGLEVEL=1 


/7PRIMO432 EXEC PGM=IDCAMS 
//7STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 


//7ATXKI 


DD VOL=SER=WTVSAM,DISP=OLD »UNIT=3330° 


//SYSPRINT DD SYSOUT=A 


/*® 


S/SYSIN DD * 


DELETE SALESMAN.K = 
ALTERNATEINDEX = 
FILE (AIXK1) . om, 


CAT (PRIMER .UCATI/UCATMRPW ) 


OS/VS example Coutput): 


IDCO550I ENTRY (R) SALES.CUST.K DELETED 

IDCO550I ENTRY (D) SALESMAN.K.D DELETED 

IDCO550I ENTRY (I) SALESMAN.K.I DELETED 

IDCO550I ENTRY (G6) SALESMAN.K DELETED 

IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCOO02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


e The FILE parameter 
7.2.1 on page 
were not recoverable , 


is required (not for MVS, 
88) to address the CRA (AIXK1). 
there would 


also see section 
If the catalog 
be no need for this parame- 


ter nor for the CRA volume to be mounted. 


° The entry types (D, G, I, and R) are explained on page 51. 
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7.18.2 


When a cluster is 


deleted, all its 


DELETE A KSDS CLUSTER (AND ITs AIX'S) 


related objects (i.e: ATs; 


PATHS) will automatically be deleted at the same time. 


DOS/VS example (input): 


// JOB DELETE KSDS 

7/ DLBL KSDS,'CUSTOMER.K', VSAM 

//7 EXTENT SYS010,HTVSAM 

// ASSGN SYS010,DISK,VOL=WTVSAM, SH 

// EXEC IDCAMS,SIZE=AUTO 7 

DELETE CUSTOMER .K - 

FILE (KSDS) ~ 
CLUSTER - 
CAT (PRIMER .UCAT1/UCATMRPH ) 

/& 


DOS/VS example Coutput): 


IDCOS550I ENTRY (R) CITY.CUST.K DELETED 
IDCO550I ENTRY (G) CITY.K DELETED 
IDCO550I ENTRY (D) CITY.K.D DELETED 
IDCOS50I ENTRY (I) CITY.K.I DELETED 
IDCOS50I ENTRY (C) CUSTOMER.K DELETED 
IDCO550I ENTRY (D) CUSTOMER.K.D DELETED 
IDCOS50I ENTRY (I) CUSTOMER.K.I DELETED 


OS/VS example Cinput): 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 

7/PRIMOGG2 EXEC PGM=IDCAMS 

//STEPCAT DD DSN=PRIMER.UCAT1 ,DISP=SHR 

//KSDS DD VOL=SER=WTVSAM, DISP=OLD ,UNIT=3330 

//SYSPRINT DD SYSOUT=A 

/(SXSIN DD * 
DELETE CUSTOMER .K - 

FILE (KSDS) - 

CLUSTER - 

CAT (PRIMER .UCATI/UCATMRPW) 

/* | 


OS/VS example (output): 


IDCO550I ENTRY (R) CITY.CUST.K DELETED 
IDCO550I ENTRY (D) CITY.K.D DELETED 
IDCO550I ENTRY (I) CITY.K.I DELETED 
IDCO550I ENTRY (G) CITY.K DELETED 
IDCO550I ENTRY (D) CUSTOMER.K.D DELETED 
IDCO550I ENTRY (I) CUSTOMER.K.I DELETED 
IDCO550I ENTRY (C) CUSTOMER.K DELETED 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0O002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


° The PURGE parameter need not to be specified, since no expira- 
tion date was specified at DEFINE time. 


° ERASE can be specified to override the data component of an AIX 
or cluster to be deleted with binary zeros. 


e The FILE parameter 


1s required (not for MVS, 


also see section 


7.2.1 on page 88) to address the CRA volume. 


° The entry types (C, D, G, I, 
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and R) are explained on page 51. 


7218.3 


DELETE AN ESDS CLUSTER CAND ITS ATIX'S) 


DOS/VS example (Cinput): 


//7 JOB DELETE ESOS 


//7 OLBL ESDS, 'CUSTOMER.E',,VSAM 

/7 EXTENT SYS010,WTVSAM | 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR 
7/7 EXEC IDCAMS, SIZE=AUTO 


OS/VS example (Cinput):. 


//PRIMER 


//7ESDS 


JOB WTSC,IBM,MSGLEVEL=1 

7/7PRIMOG52 EXEC PGM=IDCAMS . 

//STEPCAT DD OSN=PRIMER.UCAT1,DISP=SHR 

DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
//SYSPRINT DD SYSOUT=A 


DELETE CUSTOMER .E - ZISYSIN DD * 
FILE (ESDS) - DELETE CUSTOMER.E ag 
CLUSTER - FILE (ESDS) - 
CAT (PRIMER .UCAT1/UCATMRPH) CLUSTER - 
/& CAT (PRIMER .UCATL/UCATMRPNW ) 
7* 
DOS/VS example (Coutput): OS/VS example (Coutput): 
IDCOS50I ENTRY (R) CITY.CUST.E DELETED IDCO550I ENTRY (R) CITY.CUST.E DELETED 
IDCO550I ENTRY (G) CITY.E DELETED IDCO550I ENTRY (D) CITY.E.D DELETED 
IDCO550I ENTRY (D) CITY.E.D DELETED IDCO550I ENTRY (1) CITY.E.I DELETED 
IDCOS550I ENTRY (I) CITY.E.I DELETED IDCOS550I ENTRY (G) CITY.E DELETED 
TDCO550I ENTRY (R) SALES.CUST.E DELETED IDCO550I ENTRY (R) SALES.CUST.E DELETED 
IDCO550I ENTRY (G) SALESMAN.E DELETED IDCO550I ENTRY (0) SALESMAN.E.D DELETED 
IDCO550I ENTRY (D) SALESMAN.E.D DELETED IDCO5501I ENTRY (1) SALESMAN.E.I DELETED 
IDCO550I ENTRY (1) SALESMAN.E.I DELETED IDCOS550I ENTRY (G) SALESMAN.E DELETED 
IDCO550I ENTRY (C) CUSTOMER.E DELETED IDCOS550I ENTRY (D) CUSTOMER.E.D DELETED 
IDCO550I ENTRY (D) CUSTOMER.E.D DELETED IDCO550I ENTRY (C)} CUSTOMER.E DELETED 
IDCOOQO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 
‘IDC00O02I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
Notes: 


° The FILE parameter is required (not for MVS, also see section 


7.2.1 on page 88) to address the CRA volume. 


° The entry types (C, D, G, I, and R) are explained on page 51. 


Chapter 7. Access Method Services Examples 175 


7.18.4 DELETE AN RRDS CLUSTER 


DOS/VS_ example Cinput): OS/VS_ example Cinput): 
// JOB DELETE RRDS ~ /7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL RRDS, 'CUSTOMER.R', ,VSAM //PRIMOG62 EXEC PGM=IDCAMS 
// EXTENT SYS010,WTVSAM //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
// RSSGN SYS010,DISK,VOL=WTVSAM, SHR 7/RRDS DD VOL=SER=WTVSAM,DISP=OLD ,UNIT=3330 
/7/ EXEC IDCAMS, SIZE=AUTO //SYSPRINT DD SYSOUT=A 
DELETE | CUSTOMER.R - /(SYSIN DD ® 
FILE (RRDS) - DELETE | CUSTOMER.R - 
CLUSTER | - FILE (RRDS) - 
CAT (PRIMER.UCAT1/UCATMRPH) CLUSTER 
7% | CAT (PRIMER .UCAT1/UCATMRPH ) 
“*® 
DOS/VS example Coutput): OS/VS example (output): 
IDCO550I ENTRY (C) CUSTOMER.R DELETED IDCOS50I ENTRY (D) CUSTOMER.R.D DELETED 
IDCO550I ENTRY (D) CUSTOMER.R.D DELETED IDCO550I ENTRY (C) CUSTOMER.R DELETED 


IDCOOOLE FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCO0001I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


' Ipcoo0eerl IDCANS PROC. COMPL. MAX. COND.CODE WAS 0 IDCOO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
Notes: . : ( 
° The FILE parameter is required (not for MVS, also see section 


7.2.1 on page 88) to address the CRA volume. 


° The entry types (C and D) are explained on page 51. 


176 VSAM PRIMER and REFERENCE > 


7.18.5 DELETE SPACE 


DOS/VS example Cinput): 


7/7 JOB DELETE SPACE 

/7 DLBL SPACE, 'VSAM.SPACE',,VSAM 

77 EXTENT SYS010,WTVSAM; » 5114,1900 

// ASSGN SYS010,DISK,VOL=WTVSAM, SHR 

// EXEC IDCAMS,SIZE=AUTO 

DELETE (WTVSAM) SPACE = 
FILE (SPACE) ~ 
CAT (PRIMER .UCAT1/UCATMRPW ) 
7& 


DOS/VS example (Coutput): 


IDCO555I DELETE OF SPACE DID NOT CAUSE WTVSAM 
TO BE DELETED 


OS/VS example Cinput): 


//7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

7/7PRIMO472 EXEC PGM=IDCAMS 

/7STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 

//SPACE DD VOL=SER=WNTVSAN,DISP=OLD ,UNIT=3330 

//7SYSPRINT DD SYSOUT=A 

//7SYSIN DD * 
DELETE (WTVSAM) SPACE = 

FILE (SPACE) = 

CAT (PRIMER.UCATI/UCATHRPH ) 

/*® 


OS/VS example (Coutput) : 


IDCO555I DELETE OF SPACE DID NOT CAUSE WTVSAM 
TO BE DELETED 


IDCOOOQ1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMNS PROC. COMPL. MAX. COND.CODE WAS 0 IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


e "CNTVSAM) SPACE’ indicates 
WITVSAM will be deleted provided they are empty. If nonempty 
VSAM data spaces should be scratched from the VTOC and VSAM 
volume ownership should be given up, the FORCE parameter may be 
specified. FORCE cannot be specified, if the volume contains a 
VSAM catalog. | 


that all the VSAM spaces on volume 


e The FILE parameter is required (not for MVS, also see section 
7.2.1 on page 88) to address the CRA volume and to mount the 
volume (also for nonrecoverable catalogs) to change the VTOC 
(delete F1I-DSCBs describing the VSAM data spaces). 


° The message IDCO555I means, that some VSAM space is 
allocated on the volume WIVSAM, i.e., the catalog itself. 


still 
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7.18.6 DELETE USER CATALOG 


( 


DOS/VS example (input): S/VS_ example (input): | 
7/ JOB DELETE UCAT //7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
7/7 OLBL IJSYSUC, 'PRIMER.UCAT1' , »VSAM //PRIMOG82 EXEC PGM=IDCAMS 
77 EXTENT SYSO010,WTVSAM -—-« Z7STEPCAT DD DSN=PRIMER.UCAT1,DISP=OLD 
// ASSGN SYS010,DISK,VOL=WTVSAM, SHR , /7SYSPRINT DD SYSOUT=A 
// EXEC IDCAMS,SIZE=AUTO 7 7SYSIN DD * 
DELETE (PRIMER.UCATI/UCATMRPW) - DELETE (PRIMER.UCATI/UCATMRPW) - 
UCAT UCAT - 
fe 7 FORCE 
| /* 
DOS/VS example (Coutput): | OS/VS example (output): 
IDCOS550I ENTRY (U) PRIMER.UCATL DELETED IDCOS550I ENTRY (U) PRIMER.UCAT1 DELETED 


IDCOO01I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 IDC0002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Notes: 


e A user catalog can only be deleted if it is empty and is not in 
use by any other partition/region Cin OS/VS the FORCE parameter 
can be specified to delete a non-empty catalog provided it is 
not opened by any other partition/region). : 


e The master catalog connector entry pointing to that user 
| catalog is also deleted. 


e The entry type 'U' specifies a user catalog entry. All catalog 
entry types are explained on page 51. 


OS/VS_ note: 


me The FORCE parameter is not needed since the catalog is empty. 


DOS/VS_notes: 

° The user catalog to be deleted must be the current ‘Job 
catalog'. This is indicated by the DLBL/EXTENT/ASSGN state- 
ments with the filename=IJSYSUC and £ile-ID=PRIMER.UCAT!. 


° The FORCE parameter is not allowed for catalogs andis_ not 
needed since' the catalog is empty. 
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7.19 VOLUME CLEANUP 


7.19.1 VOLUME CLEANUP DOS/VS CUTILITY IKOVDU) 


A VSAM service aid has been provided to assist the system program- 
mer in maintaining the VTOC and VOL1 Labels on DASD devices. 


This aid is described together with other VSAM aids in the DOS/VS 
HANDBOOK part 2 (SY33-8572) chapter 3 section SERVICE AIDS or in 
the DOS/VS VSAM LOGIC (SY33-8562). 


It should be used with great caution since it is possible to modify 
and even scratch all or part of the DASD VTOC. 


All VSAM aids can be installed by executing the following job 


// JOB CATAL IKQVEDA IKQVDU $$BCVS04 
77 OPTION CATAL 
INCLUDE IKQCLNLK 
7/7 EXEC LNKEDT 
7 & 


To execute IK@VDU, the following job should be executed: 
// JOB IKQVDU 


// ASSGN SYS000,DISK,VOL=WTVSAM 
7/7 EXEC IKQVDU,SIZE=AUTO 


The next page contains an example of executing IKQVDU. 
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The following is an example of executing IK2VDU using the system. 
typewriter: | | 


SPECIFY FUNCTION OR 

REPLY '?' FOR OPTIONS 

READY 

? 

TO SET THE VOLUME OWNERSHIP FLAG REPLY 'SET OWNERSHIP’ 

TO SET THE CRA POINTER REPLY 'SET OWNERSHIP! 

TO RESET THE VOLUME OWNERSHIP FLAG AND CRA POINTER REPLY 'RESET OWNERSHIP’ OR ‘RESET CRA‘ 
TO SET THE SECURITY FLAG IN A Fl DSCB REPLY ‘SET SECURITY' | 
TO RESET THE SECURITY FLAG IN A Fl OSCB REPLY 'RESET SECURITY' © 
TO REMOVE A DSCB FROM THE VTOC REPLY 'SCRATCH' 

TO RENAME A DSCB REPLY ‘RENAME’ 

TO ALLOCATE A DSCB REPLY ‘ALLOCATE! 

TO REINITIATE PROCESSING REPLY 'RESTART' 

TO ALTER OR DISPLAY A DASD VOL1 LABEL 

REPLY 'CLIP LABEL=SER=N..N' OR ‘CLIP LABEL=DISPLAY' 

TO TERMINATE PROCESSING REPLY ‘END’ | 

READY 
SCRATCH DSN 

ENTER DSN 
29999994. VSAMDSPC .. T8B8486E . 73293420 

SCRATCH SECURITY PROTECTED CATALOG? 29999994. VSAMDSPC . T8B8486E . T3293420 
REPLY YES/NO 
YES | 

READY 
SCRATCH DSN 

ENTER DSN 
29999992. VSAMDSPC .T8B84870 . T54A8380 

SCRATCH SECURITY PROTECTED DATA SPACE? 29999992. VSAMDSPC.T8B84870. T54A8380 
REPLY YES/NO 
YES 

READY 
RESET OWNERSHIP 

VOLUME OWNERSHIP FLAG AND CRA POINTER RESET 

READY 
END 


Explanation of entered commands (start in column 1): 


4 all functions of IKQVDU are to be listed 


SCRATCH DSN a data set (in this case a VSAM catalog and 


a VSAM space) is to be scratched. 
Z9999994. ... = the (VTOC) data set name of the VSAM catalog 
29999992. ... = the (VTOC) data set name of the VSAM space 


RESET OWNERSHIP 


remove VSAM ownership after scratching all VSAM 
data sets | 


END = terminate utility 


180 VSAM PRIMER and REFERENCE 


7.19.2 VOLUME CLEANUP OS/VS (1/72) CALTER REMOVEVOLUMES ) 


This step is only necessary, if the volume to contain the user 
catalog or any VSAM object (as first VSAM object on that volume) is 
owned by aounknown or inaccessible VSAM catalog. It there are 
problems in defining a VSAM user catalog, or a VSAM data space ona 
volume without a catalog, this step can be executed to delete all 
VSAM information from a disk, without accessing any VSAM catalog. 


Attention: 


This function destroys VSAM catalogs/data sets on that volume. 


The VSAM master catalog name and its master password (if any) must 
be supplied as data set name. If the master catalog is not Known, 
a LISTCAT command without any parameter should be issued. If, 
however the VSAM master catalog is password protected, this pass- 
word will not be printed on the LISTCAT output. 


/7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 

//PRIMOG92 EXEC PGM=IDCAMS 

77WTVSAM DD VOL=SER=WTVSAM,DISP=OLD,UNIT=3330 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD * 
REMOVEVOLUMES( WTVSAM) 7 
MASTERPW(MCATMRPW ) - 
FILE( WTVSAM) 

/*® 


Output of Access Method Services: 


IDCO526I ALTERED ALLOC. STAT. FOR VOLUME WTVSAM IS 0 
IDCO531I ENTRY PRIMER.MCAT ALTERED 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002I IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
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If a user catalog, still cataloged in the VSAM master catalog, was 
on the old volume, this user catalog entry must be removed from the 
master catalog with the following job. 


If the user catalog is still not cataloged in the master catalog, 
the. user catalog can now be defined (see previous section 7.4 on 
page 102). ? : 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//PRIMO374 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
EXPORT PRIMER .UCAT1/UCATMRPW + 
DISCONNECT | 
/¥* 


° Output of Access Method Services: 


IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCOO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 
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7.20 DEFINE NONVSAM (COS/VS) 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 

//PRIMO582 EXEC PGM=IDCAMS 

//STEPCAT DD DSN=PRIMER.UCAT2 ,DISP=SHR 

//SYSPRINT DD SYSOUT=A 

/7SYSIN DD * 

DEFINE NONVSAM - 

(NAME( LOADKSDS ) = 
DEVT( 3330) - 
VOL(WTVSIR) ) = 
CAT (PRIMER.UCAT2/UCATMRPW ) 

/*® 


e Output of Access Method Services: 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: This object was defined in VSAM catalog PRIMER.UCATZ. The 
definition of this catalog is not included in this manual. 


7.21 DEFINE ALTAS (MVS) 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 

//7PRIMO592 EXEC PGM=IDCAMS 

//STEPCAT ODD DSN=PRIMER.UCAT2 ,DISP=SHR 

//SYSPRINT DD SYSOUT=A 

//3SYSIN DD * 

DEFINE ALIAS - 

(NAME (LOAD ) - 
RELATE (LOADKSDS) ) = 
CAT (PRIMER .UCAT2/UCATMRPH ) 

/*® 


° Output of Access Method Services: 
IDCOOO1I FUNCTION COMPL., HIGHEST COND.CODE WAS 0 


IDCO002T IDCAMS PROC. COMPL. MAX. COND.CODE WAS 0 


Note: This object was defined in VSAM catalog PRIMER.UCAT2. The 
definition of this catalog is not included in this manual. 
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8. 


1 


8.1. 


1 


MISCELLANEOUS 


PERFORMANCE 


1 CHOOSING THE TA CI- E 


Space utilization 


A given logical record size may fit some CI sizes better than 
others. Generally, large CI sizes provide better fits. Also 
some CI sizes fit a track of a given device better than others. 
For example, on a IBM 3340 track a 512 byte CI yields a poten- 
tial 6144 bytes (12 CIs), which is 67% of usable space per 
track (see section 8.2) whereas a 4096 byte CI yields £192 
bytes (2 CIs) of data on a IBM 3340 track, which is 94% of 
usable space. Assuming a 80 byte record; in one case there 
would be 72 records per track and in the other case there would 
be 102 records per track. 


Direct processing 


If direct processing is the preaominant manner of accessing the 


data, then a choice of asmall data CI is preferable. In 
general, select the smallest data CI that yields a reasonable 
space utilization. Normally 1024 or 2048 byte CIs are good, 


but on a device with large cylinder and track capacities like 
the IBM 3350 device, the index CI-size will be 4 K when using 
1K data CIs (see page 198). 


Sequential processing 


If the processing is predominantly sequential, even larger data 
CIs may be a good choice. | 


Data CI size selection: 


Figure 7 represents a summary of generally applicable choices. 
There are conditions where the next smaller or next larger CI 
than is recommended is actually a better choice based upon 
Space utilization, index CI size considerations or CPU storage 
capabilities. 
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Accessing pattern 


3330, 3350. 


2314, 3330. 


Sequential 


 $§$kip sequential 


otherwise © 


Figure 42. 


Condition or device | 


| <2 records refer- 
. enced per track | 


- Recommended 
data CI size 


or 2048 


4096, 6144 Or 8192, 


Choose CI size as 
for Direct access 


VSAM data CI size recommendations | 


8.1.2 CHOOSING THE INDEX CI SIZE (KSDS DATA SETS) 
Tf no index CI value is defined for a KSDS 


suggested) VSAM chooses the minimum index 
The VSAM chosen 
command (the fields are explained 


tion as explained in section 8.3. 
may be checked using the LISTCAT 
on page 158). 


This size can be 
This definition may help to have fewer 
level index CI can 
4“096). 


Using the index formula described in 
calculate the CI size for 502 entries 
A data set, which 
cyl), has then only two index 


CI). The disadvantage however, is the 


increased by defining 


hold a maximum of about 502. 


section 8.7 on page 


is smaller than 502 
levels 


S data set (which is 
CI based on the calcula- 
index CI-size 


CI up to 4096. 
as the highest 
entries (CI size = 


an index 
index levels, 


206) to 
would result in 4092 bytes. 
cylinders Cassumed > 
(sequence set + 1 index-set 
huge amount of buffer space 


needed to hold the index CIs (for buffers see section 8.1.5 on page 


190). 
for the 4 index CI sizes. 


The size of 
REPLICATION or IMBED is used) and thus. 
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an index CI also affects the 


Page 195 contains a table with fee AVEEage number of entries 


affects ‘performance. 


1 CA = 1. 


replication Facto: Cuhen 


Notes: 


Tf you specify an index CI size which is too small to hold all 
necessary entries for all CIs of one CA, the CA's are never filled 
to their maximum capacity. and no message is issued by VSAM _ to 
indicate this condition. Then it is better to let VSAM choose the 
index CI size. After DEFINE, a LISTCAT command can be issued and 
the entries be checked to redefine the cluster with a different 
data CA size if the index record is too big. 


If an index CI size is specified in a DEFINE command this size is 
checked based on the specified/default data CA size, and may be 
overridden without notice. | 


8.1.3 DATA SET SPACE ALLOCATION 


8.1.3.1 SMALL DATA SETS 


For data sets less than one cylinder in size it is more advanta- 
geous for space utilisation considerations (but not for pertor- 
mance) to specify the maximum number of tracks required in the 
primary allocation of the data component, one track for the non-im- 
bedded sequence set index, and no secondary definition for either 
data or index. The allocations for this data set should be set so 
that only 1 index record is allocated. This is possible if only 
one CA is allocated for the data component (see also next section). 


8.1.3.2 MULTIPLE CYLINDER DATA SETS (NOT MULTIVOLUME) 


It is usually best to calculate the number of cylinders needed for 
data in a newly created data set and specify this amount in cylir- 
ders for the primary allocation of the data component (a calcuia~ 
tion example is included in section 8.3 on page 197). 


Make the secondary allocation equal or greater than one cylinder 
but less than the primary allocation. | 


VSAM calculates the CA size based on primary and secondary alloca- 
tions. 


e If primary or secondary allocation is smaller than one cylin- 
der, the smaller value Crounded up to full tracks in case of 
RECORDS) is used as CA Size. 


° If primary and secondary allocation is larger than one cylin- 
der, the CA size is one cylinder (maximum CA size). 
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8.1.3.3 MULTIVOLUME DATA SETS 


When defining multivolume data sets, the following rules must be 
considered: | 3 : | 


1. For suballocatable multivolume data sets a VSAM data space must 
exist on all volumes specified in the VOLUMES parameter. | 


2. For unique multivolume data sets all volumes which are specified 
in the VOLUMES parameter (except the first volume in the list), 
must already be owned by the catalog, in which the multivolume 
data set is to be cataloged. | 


3. The primary or secondary allocation value must not exceed the 
maximum capacity of one volume. 


Explanation of the rules: 
Rule ij: 


e Suballocated data sets 


Before defining the multivolume data set, a DEFINE SPACE 
command must have been issued for all volumes defined in the 
VOLUMES parameter of the multivolume data set. When there 
is not enough space in a VSAM data space for a secondary 
allocation, the data space may be extended (not in DOS/VS) 
(see section 8.1.3.4). | _ 


e UNIQUE data sets 


Check if all volumes of the VOLUMES parameter (except the 
first) belong to the catalog, in which the data set is to be 
cataloged (for DOS/VS see description and notes in section 
2.9 on page 40). If not, issue a DEFINE SPACE CANDIDATE 
command for all volumes not belonging to that catalog (in 
DOS/VS DEFINE SPACE CANDIDATE is not allowed when uSing a 
recoverable catalog). After correct operation, define the 
multivolume data set. 


Note: All volumes specified in the DEFINE SPACE CANDIDATE 
command must be mounted, since the VSAM ownership bit in the 
F4-DSCB is set ON. 


In OS/VS systems when uSing recoverable catalogs alsvu a 


F1-DSCB describing the one cylinder CRA is written into the 
VTOC of each volume when the command is executed. 
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Rule 2: 


VSAM allocates the primary space on the first volume at 
DEFINE-time for non-Keyrange data sets. When loading the 
data set and the primary space is filled, the secondary 
amount of space is allocated on the first volume as long as 
there is enough space available. If there is no more space 


for secondary allocations on the first volume, VSAM allo- 
cates primary space on the second volume. Then secondary 


Space is allocated on volume 2, etc. 


Generally, VSAM always allocates primary space ona new 
volume first and continues with secondary allocations. This 
is important for the last volume. When, for example the 
Space allocation was CYL (200,50), then 200 cylinders are 
allocated, even when only 20 cylinders are needed. In this 
case, the specification CYL (50,200) would £1it better. 


-1.3.4 DATA SPACE ALLOCATION AND EXTENSION 


DOS/VS 


In DOS/VS the location and size of a VSAM data space or of a 
UNIQUE data set must be specified in an EXTENT statement. 


DOS/VS does not allow secondary space allocations for VSAM data 
Spaces or UNIQUE data sets. Therefore the use of UNIQUE data 
set should be limited to specific applications. 


VS1, SVS and MVS 
The location of a VSAM data space or of a UNIQUE data _ set 
cannot be specified with OS/VS JCL. The size is specified in 


the DEFINE SPACE or DEFINE CLUSTER ... UNIQUE command. 


When VSAM recognizes that a data space or a UNIQUE data set 
must be allocated or extended (secondary allocation), OS/DADSM 


1s automatically called to allocate the requested space. A 
data space can only be extended on one volume. When a multivo- 


lume UNIQUE data set has to be extended to the next volume 
(when there is not enough space on the first one) OS/DADSM will 
perform the allocation. 


When VSAM tries to allocate secondary space for a suballocated 
data set and there is not enough room in the VSAM data space, 
VSAM , and in sequence OS/DADSM allocates an amount of space 
either in data space secondary allocation size, or, if this is 
not enough, in the requested data set secondary allocation 
size. A data space, however can only allocate secondary 
extents if a secondary value was specified in the DEFINE SPACE 
command. | 
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8.1.4 INDEX PERFORMANCE CONSIDERATIONS 


To improve performance during processing, each sequence set index 
record may be stored with the CA it points to (by using the defini- 
tion parameter IMBED, see section 7.2.3 on page 89). This general- 
ly eliminates disk-arm movement because it is not necessary to do 
separate seeks to locate both the sequence index record and the 
data record (if the arm has not been moved by other activities 
between index and data reference). 


When the imbedded sequence set record is then duplicated on the 
first track of its CA as many times as it will fit to reduce the 
rotational delay. A data CI can never reside on the same physical 
track as the index CI. Most of the index (index sequence set 
records and all higher level index records) can reside in virtual 
storage if enough buffer storage is specified by the user, but VSAM 
does not preload index buffer(s). Depending on the type of access 
index buffers are assigned and used differently (for tfurther 
information see section 8.1.5 starting on page 190). 


8.1.5 VSAM BUFFERS (NON-SHARED RESOURCES) AND STRINGS 


Non-shared resources is the standard usage of VSAM butfers for one 
data set only. 


VSAM buffers are used by VSAM to read/write CIs from/to DASD. 


To increase performance, there are parameters (three for KSDS and 
two for ESDS and RRDS), to override the VSAM default values: 


° BUFNI ~- number of index buffers (default 1) (KSDS only) 


° BUFND | _ number of data butfers (default 2 
(DOS/VS read-only = 1)) 


e BUFSP - amount of virtual storage to be reserved for VSAM 
butfers, when opening the data set (default = 2 data buffer + 1 
index buffer) 


BUFND and BUFNI are ACB parameters (see figures 47, 48 on page 212, 
215) and in OS/VS systems also JCL parameters (see description 
starting on page 213 ‘on how to specify these parameter in the JCL 
statement). BUFSP is a DEFINE, ACB and JCL parameter (the ACB 
macro instruction is described in section 8.11.1.1 on page 217). 
Any combination of these parameters can be used. 


If a parameter is specified in JCL, this value overrides any 
previous specification of this parameter (ACB or DEFINE), provided 
it is a larger value (DOS/VS). In OS/VS the JCL overrides the ACB 
and catalog values even if it is smaller. 


If one of the parameters is specified in the ACB macro instruction 
(in the user program) this value overrides the default values, or 
in case of BUFSP the DEFINE value, even if it is a smaller value. 
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Data butfers (BUFND). 


To calculate the number of data buffers, the number of strinus 
used must be determined. A string is a request to a VSAM data 
set requiring data set positioning. VSAM stores e.g. for a 
sequential access the information about which record has been 
accessed. If different concurrent accesses to the same data 
set are necessary multiple strings are used. For multiple 
string buffers see also page 194. 


It is possible to work with multiple strings (ACB parameter 


STRNO=x). Multiple strings allow, for example, access to the 
data set directly with one string and sequentially with the 
second string. For each string there must be at least one 
butter. 

OS/VS: 


Usually the user defines the amount of strings he intends to 
use in his program CACB STRNO=x) (see also section 8.11.4 on 
page 223 and figures 47, 48 on pages 212,215). But when all 
strings are active and there is another request waiting, a new 
string is built dynamically. Dynamic string addition does not 
apply to shared resources as used in CICS and IMS. The string 
is not erased, when it is not used any more, but it can be 
reused for the next request. 


The minimum snumber of data buffers is two (1 per string + 1 £or 
splits). It 1S very important to Know that the OS/VS user can 
use only one of these two buffers. One buffer 1s always 
reserved by VSAM for splits. If 4 buffers should be used, 5 
must be specified. 


DOS/VS: 
If in DOS/VS BUFND=2 is specified, the user has access to 2 
buffers Cand not just to 1 as in OS/VS). 


Index buffers (BUFNI). 


The minimum number of index buffers is one. As described 
later, it may be advisable to have more index buffers for 
extensive index operations (direct). If multiple strings are 
used, the minimum needed is one index buffer per string. 


Buffer space (BUFSP). 


This value specifies the amount of virtual storage, which must 
be available when opening the data set. If more buffer space 
is defined than used for default buffers (2 (DOS/VS = 1 13st 
read-only) data and 1 index buffer) or specified by BUFND plus 
BUFNI, VSAM allocates more buffers in this area as determined 
by its algorithms. | 
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Note that the allocation of buffers by VSAM is based upon the 
access mode indicated in the ACB at "OPEN" time; this may 
result in inefficient buffer usage if the ACB is opened in one 
form (sequential or direct) but the majority of processing is 
in the other). | | 


8.1.5.1 BUFFERS FOR DIRECT ACCESS 


Generally, the more index buffers, the better performance that can 
be obtained. Data buffers are not important, because only one is 
used for each access. : _ : 


As there is always a top down search through the index, at least 
two index buffers should be specified, to hold the highest index cI 
in the buffer. | | 


If more than one index buffer is specified, the additional buffers 
can hold index set CIs but only one index buffer is used for the 
sequence set per string. 


If too few index buffers are specified, the result may be poor 
performance, as extensive EXCPs may have to be issued. If there 
are three index levels and only one index buffer, three index EXCPs 
are necessary to find the pointer to the correct data CI. | 


Suggested number of buffers: 
BUFNI: minimum = no. of index levels + 1 * STRNO (default = 1) 
maximum = (no. of records (CI's) in index set + 1) * STRNO 
BUFND: default = 2 (STRNO value + 1 for splits) 
(DOS/VS read-only = 1) 


The default BUFND is STRNO + 1, in turn STRNO's default is 1. 


8.1.5.2 BUFFERS FOR SKIP SEQUENTIAL ACCESS 


There is no good way to predict the number of buffers required, 
when using sKip sequential access, as only 1 data buffer is used 


Cas for direct processing) and only 1 index buffer is used for the. 


sequence set level. The suggestion below is a starting suggestion 
and should be modified by experience. 


There is no look ahead for index sequence set CIs, so there InNay be 
poor performance if the keys to access are not adjacent. 


Suggested number of buffers: 


BUFNI : default 
BUFND >: default 


1 
2 (DOS/VS read-only = 1) 


If the keys to be processed are grouped, that is concentrated on 


one or more places in the data. set, the approach for sequential 
access can be followed (see next section). | 
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8.1.5.3 BUFFERS FOR SEQUENTIAL ACCESS 


Generally, the more data buffers, the better performance that can 
be obtained. 

Index Buffers DOS/VS: 

It may be sometimes advantageous to have 2 index buffers, especial- 
ly if IMBED is not used. DOS/VS VSAM will read ahead on the next 
sequence set if 2 buffers are available. 

Index buffers OS/VS: 

For Keyed sequential access ina KSDS only one index buffer (for 
the sequence set record) is used. 

Data buffers: 

Tf multiple data buffers are specified. VSAM uses aso called 
read-ahead function. The next data control intervals are read in 


before they are needed. 


The following figure demonstrates how VSAM decreases the number of 
EXCPs when reading 1000 CIs with a different number of data buffers 


(remember in OS/VS 1 data buffer is not used).  BUFNI = 1 
(default). 
DOS/VS OS/VS | 
Gg eg Sg OORT gO eT a cma cca a A aaa aaa 
BUFND number o£ I/O overlapped BUFND number of 
EXCPs With processing EXCPS 
1 1000 No 2 1000 
2 500 No 3 500 
3 334 No uy 334 
uy 500 ~Yes 5 334 
5 334 Yes 6 225 
6 334 Yes 7 225 
7 250 Yes 8 200 


The difference between the number of EXCPs (or I/0 operations) for 
DOS/VS and OS/VS is because of different way of buffer usage. 


Suggested number of buffers: 


BUFNI 
BUFND 


1 Cor STRNO (number of strings) ) 
>4 (for multiple strings see section 8.1.5.4) 
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5.4 BUFFERS FOR MULTIPLE STRINGS 


Index buffer 


Index buffers with index set records (CIs) are used for all 


strings. Index Sequence Set records are handled as follows: 


“— records are read and used separately for each string, even 
when another string already read it into a buffer. 


- DOS/VS: Records are reread only if the needed CI is not 


already in a buffer (except with SHAREOPTION 4). 
Direct processing (data buffer) 
As described on page 191 there must be at least one buffer per 
string plus one buffer for splits. I£ STRNO=2 is specified, 
three buffers are allocated (VSAM default). | 


Sequential processing (data buffer) 


Tf multiple strings are used for sequential processing, the 
following must be considered: | | 


DOS/VS: 


494 


_ There is no buffer reserved for splits 


= There is no buffer allocated to each string, but rathnesx 
buffers are attached to the last string. In DOS/VS a strir’ 
doing sequential processing will repeatedly try to geta 
surplus buffer from strings not actively doing sequential 
processing. 


OS/VS: 


= one buffer is used for VSAM splits 
- one buffer is automatically allocated per string 


= The first sequential request is allocated all remaining 
buffers. These buffers are kept for this string until an 
ENDRE@ (end request) macro (see description in section 8.11 
starting on page 217 is issued, even when they are not 
used. A second string in this case has no read-ahead 
capability as there is no extra free buffer available. 
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Catalog 

- Minimum size on 2305, 3330, 3350 

-~ Minimum size on 2314, 3340 | 

—- Maximum number of extents (data component) 
Control area (CA) 


- Minimum size 1 track 


max. 
(so the actual size is device dependent) 
Control interval (CI) 
- Data component (minimum 512 bytes) max. 
Cin increments of 512 bytes up to 8 K, 
then in increments of 2 K up to maximum) 
~ Index component (minimum 512 bytes) max. 


(only sizes 512, 1024, 2048, 4096) 


CRA (recoverable catalog only) 


- Minimum size 
- Maximum size 


Data set 


- Maximum size of a multivolume data set 
(232 = 4 294 967 296 bytes ) 
- Maximum number of VSAM extents 
~- Maximum number of AIX per base cluster 
- Maximum no. extents/volume (UNIQUE) (COS/VS) 


Data space 
- Maximum size | 7 | 
~ Maximum number of extents (OS/VS) 


Index control interval number of entries: 


An index control interval may hold the 


“ou 


8.2 VSAM SIZES FOR DOS/VS AND OS/VS (CI-, CA-SIZES ETC.) 


45 
13 


32768 


4096 


entries (8 bytes/entry based on normal key compression): 


CI size Number of entries 

512 58 

1024 121 

2048 248 

4096 502 
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trks 
trks 


eyl 


bytes 


bytes 


cyl 


cyl 


bytes 


Vol. 


following number of 


195 


196 


- Non-spanned (max. CI-size minus 7) max. 


Key length | 


- maximum Key length 3 = 255 bytes 
~ used Key length Keyranges max. = 64 bytes 
3 | (0-63) 


Logical record length: 


32761 bytes 
(1 RDF + 1 CIDF = 7 bytes) 


-~ Spanned | | 
(max. 1 CA-size minus 10 * number CI/CA) 
(10 = 2 RDFs plus 1 CIDF) max. = < 1 cyl 


Physical record (block) sizes (no DEFINE-option) 
~ 4 sizes: 512, 1024, 2048 and (3330,3340,3350) 4096 bytes 


Each control interval is automatically divided by VSAM into an 


integral number of physical blocks (e.g. CI = 512 results in 


physical block = 512, CI = 1536 results in physical block = 
512, so 3 blocks are needed to hold one CI; CI = 6144 results 
in physical block = 2048, so 3 blocks are needed (3330 and 3350 
only, 3340 would be set to 1K), etec.). For further information 
see also page 9. 


Device characteristics 


device characteristics | number of physical blocks/track 
device trk/eyl cyl/vol 512 1024 2048 4096 
3330-1 19 “O4 20 11 6 3 
3330-11 19 808 20 11 6 3 
3340-35 12 348 12 7 * 2 
3340-70 12 696 12 7 * 2 
3350 30 555 27 15 8 4 


* 2K is not used for 3340 (would result in only 75% track 
utilization) 


Example: On a 3340, 2 physical blocks with a length of 4096 can 
be stored on one track, but only 7 physical blocks 
With each 1024 bytes. a | 
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8.3 HOW TO CALCULATE A VSAM KSDS DATA SE? 


This example shows how to calculate the following values for the 
KSDS CUSTOMER.K (see section 7.6.1 on page 106). 


° Size of data component 
e Size of index component 
° Minimum size of index control interval 


The following is assumed for the calculations: 


~ Device type is = 3330 

- Control area size (CA) = 1 cyl 

- Data control interval size (CI) = 1024 bytes 

- Physical blocksize (calculated by VSAM) = 1024 bytes 

= Record size | = 200 bytes 

~ Key length. = 5 bytes 

- Free space definition control interval = 20 % 

= Free space definition control area 3 10 % 

= Number of records to be loaded = 3000 

~ Index options defined | = IMBED/ 
REPLICATE 


The calculations are shown on the next page. 
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Based on the previous. specifications the following can be calculat- 
ed (see are notes on the following page): ? 


e Data component: 


i 
1S) 


(1) number maximum records/CI ((€1024-10)7200) 
min.free bytes (20% * CIsize)(see page 88) = 204 


number loaded records (1024-10-204) 7 200 = 4 
(2) number physical blocks/track = 11 
(3) number max. CI/CA (11*18) | = 198 
(1 cyl=19 trks - 1 track for index seq.set) 
number loaded CI/CA (198-10% freespace) = 178 
number loaded records/cyl (4*178) = 712 
Total space for data component (3000/7712) (rounded) = 5 cyl 
e Index component 
sequence set: (included in data component) = 0 trks 
index set: 
savoriation for one sequence set index ene sy 
(1 entry per data CI): 
(4) key compressed = 3 
(5) control bytes = 2 
(6) pointer to a data CI ina CA = 1 
total bytes per seq. set or index set entry = 6 
(7) number index entr. per index CI (data CI/CA)= 198 
length index entr. per index CI (198*6) = 1188 
control fields/index CI(Cheader,RDF,CIDF) = 31 
total (minimum) length/index CI bytes = 1219 


Minimum index CI-sizge (see CI sizes page 195) = 2048 


(8) number of different index CI records in 
sequence set (included in data component) 
number of index CIs index set 


toeuoou 
— — (5} 


space for ee set = CI/7track (REPLICATE) ) trk 
Total space for index component _ = 1 trk 


Notes: 


(1) The value (1024-10) is CI length minus 10 bytes for 2 
RDFs and 1 CIDF for fixed length records. For variable 
length records 19 bytes (for 5 RDFs and 1 CIDF) are. 
needed, but calculations are not affected. | 
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(2) On IBM 3330, eleven physical blocks with 1024 bytes can 
be stored on one track (see physical block sizes on page 
196). 


(3) The value (11*18) is the number of physical blocks per 
track multiplied by the number of data tracks per cylin- 
der (19 minus.1 for the sequence set control intervel 
(IMBED)). 


(4) For index calculations 3 bytes can be used as an average 


compressed key length. This average value is almost 
independent of the actual key length and is also valid 
for longer keys. Only in very unusual Key structures, 


this value may be higher. 


As a guidance if keys are compressed well, smaller keys 
(5-15 bytes) can compress to 3-5 bytes and longer. Keys 
(20-30 bytes) can compress to 6-7 bytes. 


Index key compression is explained in section 8.6 on page 
203. The formula for the index control interval size is 
explained in section 8.7 on page 206. 


(5) The control fields have a fixed length of 2 bytes (Cused 
for the key compression). 


(6) The length of the pointer (Ca control interval number) is 
usually 1 byte for the sequence set and 2 bytes for all 
higher index levels (the index set). 


(7) For calculation of the minimum index CI size, the maximum 
number of entries per CA must be used. 


(8) On IBM 3330 six physical blocks with the length of 2048 
bytes can be stored on one track (see physical block 
sizes on page 196). See also index CI size formula 
explained on page 206. 


One index CI of the sequence set addresses one CA. Since 
in our case 1 CA = 1 cylinder and the size of the KSDS is 
5 cylinders, 5 aundex CI sequence set records are 
required. They are imbedded, that is replicated on the 
first track of the corresponding CA and do not occupy 
Space in the index component itself. Then one index set 
CI would be enough to accommodate 5 entries. The minimum 
allocation of 1 track for an index CA (6 CI per CA) was 
chosen by VSAM. 


8.4 LOADING A KSDS WITH DIFFERENT FREE SPACE 


As discussed in section 7.2.2 on page 88, free space to be held 
free for later insertions can be defined in the DEFINE command. 
This value can be changed with the ALTER command. The following 
discussion shows an example using these two commands. 
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Assuming a large KSDS data set is to contain records with keys from 
1 - 300000. It is expected to have no inserts in Keyrange 1 - 
100000, some inserts in Keyrange 100001 - 200000 and heavy inserts 
in Keyrange 200001 - 300000. 


An ideal data structure at loading time would be for example: 
° Keyrange 1 —- 100000 no free space 


° Keyrange 100001 - 200000 5% CA free space 
° Keyrange 200001 - 300000 5% CI and 20% CA free space 


This structure can be built as follows: 


1. DEFINE CLUSTER with FREESPACE (0 0), or without any FREESPACE 
parameter. 


2. Load records 1 - 100000 with REPRO or any user program using 
sequential insertion technique. 


3. CLOSE the data set. 


4. Change the FREESPACE value of the cluster with the Access 
Method Services command ‘ALTER clustername FREESPACE (0 5)". 


5. Load records 100001 - 200000 with REPRO or any user program 
using sequential insertion technique. 


6. CLOSE the data set. / 


7. Change the FREESPACE value of the cluster with the Access 
Method Services command ‘ALTER clustername FREESPACE (5 20)". 


8. Load records 200001 - 300000 with REPRO or any user program 
| using sequential insertion technique. 


As result, this procedure: 


* prevents wasting space (as it would be, if e.g FREESPACE (0 10) 
would be defined for the whole data set) 


e minimizes CI or CA splits (for the first inserts there would be 
a huge number of CI or CA splits, if e.g. FREESPACE (0 0) would 
be defined for the whole data set). 


NOTE: A sequential insertion technigue must be used to load the 
parts of the data set to reserve the amount of FREESPACE in the 
data set (see also section 8.8 on page 207, which describes this 
technique). | 


Subsequent sequential insertions to any point of the data set will 
preserve FREESPACE according to final value left in the catalog. 
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8.5 CONTROL INTERVAL SPLIT (DIRECT INSERT) 


T£ the record to be inserted will not £it in the control interval, 
a control interval split takes place as illustrated in the follouw- 
ing example. 


Assume the following control area contains 4 control intervals. 
A free space value has been specified to reserve 25% of the 
number of CIs to be used for later insertions. This results in 
one free control interval per CA (25% of 4 control intervals). 


index 


set . , 


a 


el e> =. =| «|» 


logical 


records 


free control interval 


c£ = control fields (RDFs, CIDF) 
fp = pointer to free CI 
u = unused space 


Figure 43. Control interval split (1 of 2) 


Now record 70 is to be inserted. In this example, the second 
data control interval is read by VSAM into a VSAM buffer. By 
examining the control fields VSAM determines that there is not 
enough free space available for this record. About half of the 
control interval is moved £rom this buffer to a second empty 
buffer (in OS/VS systems it is already reserved for control 
interval split by VSAM; in DOS/VS systems it will be allocated 
when needed). Insert new record into appropriate buffer. Ds oar 
as in this example, there is an empty control interval avail- 
able Cat the end of the control area), the second buffer is 
Written into this empty control interval on auxiliary storage. 
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After this, the physical sequence of control intervals within 


the CA no longer represents the correct sequence of the logical © 
records. Therefore, the primary index is updated to reflect 


this condition. 


The first buffer is written back into the old control interval 


on auxiliary storage (the sequence of writing buffers back is 


different in DOS/VS systems). © 


index ne 
sequence 
set aap 
logical 

records 


cf = control fields (RDFs, CIDF) 

u = unused space | 

* = entry added due to control interval split 
KK =x 


pointer changed due to control interval split 


Figure 43. Control interval split (2 of 2) 


If there is no free control interval in the. control area, the 
record is not inserted until a control area split takes place (in 


DOS/VS the CA is scanned for an ‘erased’ CI; if one found, it its 


used; if not, then the CA split proceeds) to provide free control 
intervals. 7 | 


VSAM obtains a new empty control area from the end of the data set. 
Then the whole control area is split by reading about half of the 
control area into virtual storage and writing it back to auxiliary 
storage into the new control area. = a 


202 VSAM PRIMER and REFERENCE 


The minimum amount of VSAM buffers used for the CA split is STRNO+1 
(STRNO is the number of strings specified; see description on page 
191). 

Logically coincident with writing the ‘new’ CA to auxiliary 
storage, a sequence set record is constructed for it and written, 
the 'old' CA is rewritten, and the sequence set for the old CA is 
first adjusted and then rewritten. 


After the control area split, the control interval split takes 
place and the record is inserted. : 


$8.6 KEY COMPRESSION 


As described in section 2.4 on page 13, 18 the index sequence set 
contains an entry for each data CI of a KSDS. 


Each entry consists of the highest key in that CI and an RBA 
offset. To shorten the size of the index entry, the keys are 
compressed by VSAM routines. This is called key compression. 


The key compression uses ront Ke compression and rear kKey 
compression. 


The following example shows how Key compression works. 


Assuming the following CIs exist ina cluster: 
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For s#front Key _compression the highest key of the first CI is 
compared and all identical values starting from left are 
compressed. Using the previous CIs the following compression would | 
take place: | | 


Full key Front compressed Key 


10009 10009 
10080 
10080 ===80 
10333 
10333 ==333 
14028 
14028 =4028 


For the rear Key compression the highest Key of the first CI is 
compared with the lowest key of the second CI, and so on. Value by 
value is compressed starting from the right as long as the second 
value is higher. 


Full key Rear compressed Key 


10009 1000- 

10052 | 

10080 100-- 

10222 

10333 10--~ 

14021 x 
14028 14028 


VSAM uses both types of compression. To indicate how many bytes are 
compressed and how large the compressed key is, two one-byte fields 
are used. The ‘'F' field contains the number of front Key 
compressed bytes. The 'L' field contains the residual Key length. 
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Combining front and rear key compression the compressed keys and 
their F+tL fields are as follows ('=' is front and ‘'-' is rear Key 
compression): 


Full key Full compressed Key E L 
CI 1 10009 1000- 0 4 
CI 2 10080 ===-- 3 0 
CI 3 10333 = 2 0 
CI 4 14028 14028 | 0 5 
VSAM reconstructs a compressed Key as follows: 
e Front compressed values are taken from the previous uncom- 


pressed Key. 


e Rear compressed values are substituted by X'FF'! 


The previously compressed Keys would then be reconstructed as 
follows ('£' represents the hex value X'FF'"): 


Full Key Full compressed Key F L reconstructed Key 
CI 1 10009 1000- 0 uy 1000£ 
CI 2 10080 ===-- 3 0 100££ 
CI 3 10333 ==--- 2 0 10£££ 
CI 4 14028 14028 0 865 14028 


Based on the Key compression, VSAM determines, into which CI a new 

record has to be inserted. A record with the value 10088 would he 
inserted into CI 2 since the value is lower than 100££ (£=X'FF').A 
record with the value of 10100 would be inserted into CI 3. 


Single field Keys do compress well. Larger Keys (20-30 bytes) 


compress out to 8 or 9 bytes including control information. Smaller 
keys (5-15 bytes) can compress to 3 to 5 bytes. 
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8.7 INDEX CI SIZE FORMULA 


The formula used to determine the appropriate index CI size in 
DOS/VS and OS/VS systems is: 


8*¥(CCIS/CAI+2°0°(CIS/CA)**0.5)+31 


In OS/VS systems additionally another formula (for minimum calcula- 
tion) is used:. | . 


2* (Keylength+2)+(3*(CI/CA) )+31 


Explanations: 


Formula 1: 


8*(CI/CA) 


8 bytes per CI = (3 bytes compressed Key + 
F + L + 3 bytes RBA displacement value; £for 
compressed key, F and L see section 8.6 on 
page 203) 


2*CCCI/CA) **0.5) 


calculation for the index segment entries 
(2 bytes * number of entries). 


31 = index control fields (24 bytes header + 3 
bytes RDF + 4 bytes CIDF). 


Formula 2 (OS/VS): 


2*(Keylength+2) 


2 CI/7CA (minimum) * uncompressed Key + L + 
F €£or compressed key, F and L see section 
8.6 on page 203). 


(3*(CI/SCA)) number o£ RBA pointer (displacement values) 


K 3 (maximum size is 3 bytes). 


31 = index control fields (24 bytes header + 3 
bytes RDF + 4 bytes CIDF). 


Note: The average number of entries per control interval is listed 
on page 195. 
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8.8 SINGLE/MASS-INSERTION 


As described in section 2.6 starting on page 22 various techniques 
can be used to enter data into a KSDS: 


° Keyed direct processing 
e Keyed sequential processing 
° Keyed skip-sequential processing 


The following discussion tries to show the differences between 
direct processing and sequential processing when inserting records 
between existing records. 


Mass insertion is a technique which is automatically used by VSAM 
when: 


° The data set is opened for output (ACB MACRF=OUT) 
o- Sequential insertion technique is used (RPL OPTCD=SEQ) 


° The records to be inserted are sorted in ascending sequence and 
= ee to be loaded into an empty data set, or 
= fit between 2 existing records, or 
= are to be loaded at the end of a data set. 


This technique is, for example, automatically used, when sorted 
records are loaded with REPRO into an empty data set. 


Mass insertion reserves defined FREESPACE and does not perform CI- 
or CA splits (only 1 CI split is executed, if records are to be 
inserted between existing records). This improves loading time. 


As there are no CI splits (except the first) this technique reduces 
DASD space usage dramatically. 


The following examples show the difference in space usage when 
inserting adjacent records with direct insertions or with sequen- 
tial insertion (mass insert). 


Note that buffers are written back to disk each time after inser- 
tion when using direct insertion and delayed (depending on the 
amount of available buffers) when using mass insertion. 


Due to space limitations only the sequence of 9 records to be 
inserted can be shown. The insertion of only 9 records does not 
show a great enhancement (in disk space usage) of mass insertion 
(with FREESPACE) over direct insertion, but it is more effective, 
1£ more records are to be inserted. | 
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In the following example records 31 to 39 are to be inserted with 
direct insertio technique (a search argument is supplied by the 
user for each record) into a VSAM data set already containing 
records 10, 13, 15, and 55 (first line). 


The ra of the 4 CIs is shown after each insert. 


COCCI CECI 


eels 


Insert record 32 (the CI must be split): 


solvates] | Jlasfoe)ss] | JET TTT JLT tt UT I 


Insert record 33: 


Ci eS Coe Reese eee 


taser record 34: 


eels! Jee Es| TOC 


Insert record 35 (the CI must be split): 


“Pls ee eb. ICL 


Insert record 36: 


EE KESEE | ESE bee ahinliedked 


Insert record 37: 


ia] a] sa] |) [esses] pit dt | 


Insert record 38 (the CI must be split): 


elf) LT )b[=[ F ] bse] [ Pls 1 


Insert record 39: 
relshs| | EP.) ]bbs[[ [|b bebe] 


Result: 3 CIs were split and approximately 50% (in this example 
40%) of their space wasted, because no records will be inserted in 
the free space, Since adjacent records are already stored. 


Figure “4. Insertions: Direct insertion 
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In the following example records 31 to 39 are to be inserted with 
mass sequential insertion technique into a data set already 
containing records 10, 13, 15, and 55 (first line). Mo FREESPACE 
value was defined for the data set. 


The content of the 4 CIs is shown after each insert. 


elt ICCC DICLLENICLLLE 


Insert record 31: 


COCO Coo 


Insert record 32 (the CI is split at the point of insertion): 


ss] TTT LET ET LE Et 


Insert record 33 (a free CI is used, no split): 


ss] TTT UL ETT ILE Et 


Insert record 34 


oltatis)ssfea][ss] | TL |lse]a] 1 | ILE TT 


Insert record 35: 


jrofsafssfesfse] [ss] | | | Jfaeqesest | JE TT Tt 


Insert record 36: 


elsb|[_) OPE ICT 


Insert record 37: 


KORE EE) ptt ta 


Insert record 38 (a free CI is used, no split): 


ss] | | tdi eet LL 


Insert record 39: 
tojtsi1s|si}szi{ss} | | | |[ss}ss{ss}s6js7]|se/se] || 


Result: There is only 1 CI split at the point of insertions. Then 
the next free CI in the CA (or, if necessary the next free CI in 
the next free CA) is used for further insertions. 


Figure 45. Insertions: Mass insertion (no FREESPACE) 
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In the following example records 31-39 are to be inserted with mass 
sequential insertion technique into a data set already containing 
records 10,13,15, and 55. A FREESPACE value of 20% free CI space 
was defined for the data set, which results in one free record per. 
CI. The content of the 4 CIs is shown after each insert. 


GREEDCOCCOCOooTT 


ald he record 31: 


eb lts|C TC OCLLLNICLT LT 


DE record 32 (CI split at point of insertion): 


ee eee 


Insert record 33 (a new free CI is used to avoid further splits): 


1a] 13} s8] 34/32 Fi a eat TET EE EE 


Insert record 34: . 


COSC ea eee a 


aces record 35: 


jtojsa}esfentaa) iss] | TT Slaefeves] | JLT TTT 


Insert record 36: 


jrolsafesias}aa|{ss] | | | |fasjaefestee] |] T | tT | 


Insert record 37 (a new free CI is used due to FREESPACE def.): 


toss} dsjas}ae} iss] | | | |festss[sstae] |fer] ft | 


Insert record 38: 


ss] | 1 | jiespestesfee] J fs7fse] | 


Insert record 39: 
tojrsiis/sifaz}iss} | | | |{sa[asissise] 


Result: The first control interval is filled independent of the 
FREESPACE definition, because the new records were inserted in the 
middle Cand not at the end) of the control interval. Only for 
insertions at the end (which is the case starting with record 35). 
the amount of specified FREESPACE is held free. There is only 1 CI 
split at the point of insertions. Then the next free CI in the CA 
Cor, if necessary the next free CI in the next free CA) is used for 
further insertions (1 record is held free per CI). | 


Figure 46. Insertions: Mass insertion (with FREESPACE) 
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8.9 VSAM RELATED PARAMETERS IN THE JCL 


8.9.1 DOS/VS JCL PARAMETER 


Since all VSAM data set related information is stored in a VSAM 
catalog, the JCL parameters for VSAM data sets are different. 


// DLBL ...,VSAML,BUFSP=n]J[,CAT=filename ] 


// EXTENT SYSnnn,volidl,,,start,# of tracks] 
th IN a eee 
required for: all VSAM files SPACEs, UNIQUE data sets, 
and DEFINE MCAT/UCAT 
(Not needed for suballocated 
data sets). 


4/7 EXEC prog,SIZE=mk 


NOTE: Parameter in brackets are optional. 


Legend: \ 
n = number of bytes for buffer space. This value, if higher, 
Will replace the value indicated in the catalog or in 
the program. 
filename = name of the catalog that owns the data set. It overrides 
defaults which are the master or the current user 
catalog (also called 'job catalog'). 
m = number of K bytes occupied by the program. The remaining 


GETVIS will be used as indicated in sections 9.2.1 and 
64 Phe 
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8.9.2 DOS/VS JCL TO VSAM MACRO RELATIONSHIP 


// DLBL filename,['file-ID'],,{VSAM][,BUFSP=n][,CAT=name ] 
a | [, BLKSIZE=n] 


{label ] RPL {[ACB=address ] 
{,OPTCD=([DIRISEQISKP] 
es ae 


[, DDNAME=ddnane ] 
[,BUFND=number ] 
[,BUFNI=number ] 
[,BUFSP=number ] ; 
[,MACRF=C(IDIR][,SEQ][,SKP] 
[,INJ[,o0uT] 
[,NRSJ[,RST] 


[,STRNO=number ] 
[{,PASSWD=address]_ 
[,EXLST=addzress ] 


[label ] ) 


) 


Figure 47. DOS/VS JCL to VSAM macro relationship 
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8.9.3 OS/VS JCL PARAMETER 
Since all VSAM data set related information is stored in a VSAM 
catalog, the JCL parameters for VSAM data sets are different. 
The DD statement has the following format: 
//ddname DD DSN=dsname,DISP={OLDISHR}[,UNIT=unit ] 
[, VOL=SER=volser][,AMP=list] 
DISP=OLDIPASS usage like in normal OS/VS 
DISP=SHR | for shared data sets (the amount of sharing is 
specified with the SHAREOPTION parameter at 


DEFINE time (Cor changed with ALTER) 


UNIT and VOL only necessary for Subset Mount (see page 216) 


AMP has the following parameters: 


[AMP=['AMORG' ] only necessary if UNIT and VOL specified (see 


page 216) | 
[,*BUFND=number' ] overrides ACB specification 
[,"BUFNI=number' ] overrides ACB specification 
[,*BUFSP=number' ] overrides ACB specification 
[,'"STRNO=number' ] overrides ACB specification 
[,"*SYNAD=modulename' ] overrides EXLST specification 
[,*TRACE' ] use With GTF for OPEN/CLOSE/EOV 
[,"CROPS={RCKINCKINREINRC}'] Checkpt. Restart Opt. (6026-3784) 
[,*OPTCD={IILIIL}' ] ISAM options (for ISAM Interface) 
[ 


"RECFM={FIFBIVIVB}'}] J] ISAM options (for ISAM Interface) 


If data sets residing in a user catalog are to be accessed this 
user catalog must be specified either with a JOBCAT DD statement 
(the user catalog is used for all steps of the job) or with a 
STEPCAT DD statement (the user catalog is used for this step only). 


In MVS JOBCAT or STEPCAT DD statements are not necessary if the 
high level qualifier of the data set name is the same name as the 
name of a user catalog or the ALIAS of one. A STEPCAT DD statement 
overrides a JOBCAT DD statement. 


The JOBCAT DD statement must follow the JOB statement (after a 
JOBLIB DD statement if available) before the EXEC statement. 


The STEPCAT DD statement must follow the EXEC statement and can be 
placed anywhere among the other DD statements. 


JOBCAT and STEPCAT DD statements may be concatenated to specify 
more than one user catalog to be used for the job or the step. 
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The format of these statements is as follows: 


//SJOBCAT DD DSN=usercatalogname,DISP=SHR 
//STEPCAT DD DSN=usercatalogname,DISP=SHR 


8.9.3.1 OQOS/7VS JCL DDNAME/DSNAME SHARING 


If a VSAM data set has to be accessed directly and sequentially 
simultaneously either multiple string processing or DDNAME/DSNAME 


sharing can be used. 


The following applies: 


e DDNAME/DSNAME sharing works like multiple string processing 


from the VSAM point of view 
® VSAM maintains integrity 


° CIs obtained for UPDATE are ‘locked' 


° "Exclusive control error’ is returned if access to ‘locked’ 


is attempted 


e multiple copies of the same CI can be in storage 


The following is a short example of how to use DDNAME sharing: 


Z/NSAM1 DD DSN=cluster,DISP=SHR 


RCE)! 280% DDNAME=VSAM1,MACRF=DDN 
RCBZ s8eenG.x DDNAME=VSAM1,MACRF=DDN 


The following is a short example of how to use DSNAME sharing: 


J/VSAM1 DD DSN=cluster,DISP=SHR 
//NSAM2 DD DSN=cluster,DISP=SHR 


ACBY | ess DDNAME=VSAM1,MACRF=DSN 
ACES: snes DDNAME=VSAM2Z,MACRF=DSN 
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8.9.4 OS/VS JCL TO VSAM MACRO RELATIONSHIP 


//Adname DD DSNAME=dsname,DISP={OLDISHR} 
eae 


[label ] C(address[,(Coptions)],...) | 


ee 
ee: ae 


[label ] RPL fACR-address Oe Se 
[,OPTCD=([DIRISEGISKP] 


>[ , DDNAME=ddnane ] 
[,BUFND=number ] 
[,BUFNI=number ] 
[,BUFSP=number ] 
[,MACRF=([DIR][,SEQ][,SKP] 
[,IN]{,0uUT] 
[,NRS]JI[,RST] 
[,STRNO=number ] 
[,PASSWD=address ] 
[,EXLST=address ]—-—_- 


[label ] EXLST [{JRNAD=(addressI[,AINJI[,L]) 


] 
[SYNAD=CaddressI[,AINIJ[,1L]) ] 


Figure 48. OS/VS JCL to VSAM macro relationship 
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8.10 SUBSET MOUNT 


"Subset Mount’ is not part of VSAM and must be used very carefully 
to avoid mounting and demounting problems.: If possible, ‘Subset 
Mount’ should be used for read-only operations. 


Special problem areas are: 


o Index and data component on different device types 
° Extending a data set onto a new volume 
e Using recoverable catalogs 


8.10.1 SUBSET MOUNT (DOS/VS) 


In DOS/VS for all but Keyrange data sets, all the volumes of a VSAM 
data set must be specified in the EXTENT statement. If only a 
Specific volume of a multivolume Keyrange data set should pc 
mounted, only this volume may be specified in the EXTENT oe cemeny 
(so this is (the same as OS/VS subset mount). 


8.10.2 SUBSET MOUNT (OS/VS) 


In OS/VS a VSAM data set and its volumes are found by specifying 
only the cluster name and, if necessary, the catalog name. OS/VS 
then uses the catalog information and issues a mount request for 
all volumes of the data set. 


If a multivolume data set is to be opened, normally all volumes are 
mounted. 


If the user knows however, on which volume the required data is 
stored, (i1£ key ranges are used, it is very easy to determine, 
which volume contains the data) he can mount only this volume with 
subset mount (mounting only one volume of a multivolume data set 
may be desirable, if insufficient drives are available or to reduce 
mount time). | 


The following example shows how to use OS/VS subset mount: 


e Assuming the data set KSDSKEYR was defined with key ranges 
using three volumes (V1: Keys A-F, V2: Keys G-P, V3: Keys @-Z) 
(see Key range example 1 in section 7.2.4). 


If the specific job only uses keys between G and P, only volume 
VZ need be mounted. 
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OS/VS JCL for normal and for subset mount: 


= Normal mount (Call 4 volumes) 
//DD1 DD DSN=KSDSKEYR,DISP=OLD 
= OS/VS subset mount Conly volume V2) 


7/001 DD DSN=KSDSKEYR,DISP=OLD,UNIT=3330, 
// VOL=SER=VZ,AMP="AMORG' 


AMP='AMORG’' may be specified to specify buffers, etc. 


If there is any access to a part of the data set, which is 
not on volume V2, an error message is issued (no additional 
volume is mounted). 


8.11 VSAM ASSEMBLER MACROS (SHORT DESCRIPTION) 


The macros provided to define and process VSAM data sets are 
divided into control block macros and reguest macros. 


The control block macros are used to define, modify, display, and 
test the contents of VSAM control blocks and lists. The request 
macros are used to specify the processing action (read, write, 
etc.) to be taken on data and index records. 


-11.1 VSAM CONTROL BLOCK MACROS 


8.i11.1.1 ACB (GENERATE AN ACCESS CONTROL BLOCK) 


The ACB macro causes an access control block to be generated during 
program assembly. One ACB Cor GENCB, see section 8.11.1.4 on page 
219) macro must be specified ina program for each VSAM data set 
that is to be processed by the program. More that one ACB can be 
specified in a program for the same VSAM data set. In this case, 
the ACB’s are connected to the same VSAM control block structure 
and the same set of I/O buffers is used for all requests issued to 
the data set (see section 8.9.3.1 on page 214). The access control 
block for a VSAM data set must be opened before any processing of 
the data set can occur. 


The ACB specifies the following for a VSAM data set: name of the 
DD statement (OS/VS) ox the DLBL ‘filename’ (DOS/VS) for the data 
set, address of a list of exit routine addresses for user-written 
exit routines, buffer space requirements, the password required for 
the type of processing to be done, all processing options to be 
used with the data set (keyed, addressed, and/or control interval, 
sequential, skip-sequential, and/or direct, etce.), and the number 
of requests that can be outstanding concurrently for the data set 
using this ACB. : 
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The EXLST macro is used to define a list of the addresses of the 
user-written exit routines that are to be entered when certain 
conditions occur during the processing of a VSAM data set. The 

EXLST macro causes an exit list to be generated during program 
assembly. 7 — 


Exit to a user-written routine can be taken when end of data set is 
reached (CEODAD exit), a logical error occurs CLERAD exit), an 
uncorrectable physical I/0 error occurs (SYNAD exit), oz to perform 


a journaling operation Saag exit). Each exit routine can be 
marked active or inactive. An exit routine that is inactive is not 
entered when its associated condition occurs. The exits to be used 


during the processing of a given VSAM data set are specified in its 
ACB (the address of an EXLST macro can be ou Vets More that one 


ACB can specify the same EXLST macro. 


The journaling exit ies. Karen by VSAM at the following. times: 


whenever a GET, PUT, or ERASE macro is issued to the VSAM data set; 


each time data is shifted within a control interval or moved to 


another control interval (kKey- peauenced data sets only); and each 


time a physical I/0 error occurs. 


A user-written journaling routine can be used, therefore, to keep 
track of any RBA changes for the logical records of a key- sequenced 
data set, if it is to be processed by RBA, and/or to record the 


VSAM requests that are processed against a VSAM data set (for 


recovery and reconstruction purposes, fox example). 


8.11.1.3 RPL (GENERATE A REQUEST PARAMETER LIST) 


An RPL macro is used to generate a request parameter list during 
program assembly. This list defines a request for processing. 
Certain request macros (GET, PUT, ERASE, POINT, CHECK, ENDREQ, 
GETIX, and PUTIX) must specify the address of a request parameter 
list to indicate the processing to he performed. The same RPL can 
be specified in more than one type of a macro. 


An RPL macro specifies the Soi ieuinee tne ACB of ene qaea set with 
which it is to be used (multiple RPL macros can. specify the sere 
ACB); the size and address of a work area if logical records are 
not to be processed in an I/O buffer; the search argument to he 
used during direct retrieval, gkip- sequential retrieval, and 
positioning (full Key, generic key, RBA, or relative record 
number) ; address of an ECB if this is. an asynchronous request 
(optional parameter); the type of processing for this. request, such 
as keyed or addressed, sequential or direct, forward or backward, 
synchronous or asynchronous request (COS/VS. Ber Ga (ete. 


When a synchronous pediege. as specie isa: in the RPL indicated by a. 


GET or PUT macro, control is not. returned to the instruction after 
the GET/PUT macro until processing of the request is completed. The 
logical record is then available for processing. | 
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In OS/VS when an asynchronous request is specified, control returns 
to the instruction after the GET/PUT macro as soon as the request 
has been scheduled. The user must then test for completion of the 
I/O operation (usually uSing a CHECK macro). Asynchronous proces-— 
sing of a request permits the overlap of I/0 operations with 
program execution and is particularly useful with skip-sequentialL 
and direct processing. Up to 255 asynchronous requests (RPL's) can 
be outstanding concurrently for the same VSAM data set. 


Two or more RPLs can be chained together via a pointer field in the 
RPL itself. A chained parameter list can be used to read or write 
several records (one for each RPL in the chain) uSing one GET or 
PUT macro instead of multiple macros. Chained parameter lists can 
be used only to retrieve several existing records or to add several 
new records. It cannot be used to retrieve-for-update, update, or 
delete existing records. 


8.11.1.4 GENCB (GENERATE A CONTROL BLOCK OR LIST) 


The GENCB macro can be used to generate an ACB, EXLST, or RPL 
during program execution instead of program assembly. The GENCB 
macros can be used to eliminate changing these control macros and 
reassembling VSAM programs when control block formats change in new 
versions of VSAM. 


The same parameters can be specified in a GENCB macro as in ACB, 
EXLST, and RPL macros. However, a GENCB macro can specify that 
multiple copies of the control block are to be generated and 
parameter values can be specified in more ways (such as in general 
registers). 


8.11.1.5 MODCB (MODIFY CONTENTS OF CONTROL BLOCK OR LIST) 


The MODCB macro is used to change, during program execution, the 
contents of an unopened ACB, an EXLST, or an inactive RPL (Cone not 
currently involved in a processing operation). 


8.11.1.6 SHOWCB (DISPLAY CONTENTS OF CONTROL BLOCK/LIST) 


The SHOWCB macro issued to place the contents of user-specified 
fields of an ACB, EXLST, or RPL in a user-specified work area. 


8.11.1.7 TESTCB (TEST CONTENTS OF CONTROL BLOCK OR LIST) 
The TESTCB macro is used to have VSAM compare a_ user-specified 


value with a field in an ACB, EXLST, or RPL. The condition code ina 
the PSW is set to indicate the results of the comparison. 
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8.11.1.8 SHOWCAT (DISPLAY FIELDS IN A VSAM CATALOG) 


The SHOWCAT macro can be used to cause selected fields from the 
catalog entry for a specified data set to be moved to a user-pro- 
vided work area. The data set whose catalog entry is being inspect- 
ed need not be open in order for the SHOWCAT macro to be issued. 


8.11.2 VSAM REQUEST MACROS 


8.11.2.1 OPEN 


A VSAM data set must be opened before it can be processed by other 
request macros. The OPEN macro provides the same types of proces- 
Sing functions for VSAM data sets as for other types of data sets. 
OPEN causes the volumes of the VSAM data set to be mounted if 
necessary, constructs the control blocks required (in addition to 
those already created by EXLST, ACB, and GENCB macros) £for the type 
of processing to be done, overrides information in the ACB and 


EXLST with any parameters specified in the DD statement for the 


data set, causes the loading into virtual storage of any VSAM 
routines required (in addition to the resident VSAM routines) for 
the processing specified, and verifies that the password given is 
correct. Any parameter not specified via job control or the ACB il 
taken from the catalog entry for the data set. | | 


Both sequential and direct processing can be performed on a VSAM 
data set using one OPEN macro and one ACB. Closing and reopening of 
the data set to switch modes, as is required for an ISAM data set, 
is not necessary. | 


8.11.2.2 GET 


This macro is used for simple retrieval and for retrieval for. 


update (GET for update) operations. The RPL specified by a GET 
macro indicates whether the request is for a retrieval only or a 
retrieve and update operation. A record that was retrieved by a 
GET-for-update request need not be written back if it is not to he 
changed. 


Locate mode (logical record made available in the input buffer) can 
be specified for retrieval only (GET) and retrieve for update 
without record length change (GET-for-update) operations. In the 
latter case, however, the updated record must be placed in a work 
area before it is rewritten. Move mode (logical record made avail- 
able in a work area) is supported for all read and write requests 
and is required for all write (PUT and ERASE) operations. | 
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8.11.2.3 Put 


This macro is used to write a new record ina data set during its 
creation or to insert a new record in an existing data set. A PUT 
for update is used to change the contents of an existing record 
Cupdate it or mark it deleted with a user-defined deletion indica- 
tion). A PUT-for-update request must be preceded by a GET- 
for-update request. Write verification (automatic reading by DASD 
hardware after each write operation) is optional and can be speci- 
fied with the DEFINE parameter WRITECHECK (not suggested). 


8.11.2.4 ERASE 


This macro is used to delete a logical record froma Key- 
sequenced or relative record data set. The record is physically 
removed from the data set. An ERASE macro must be preceded by a 
GET-~for-update macro. 


8.11.2.5 POINT 


This macro is used to position VSAM to a particular logical record 
in the data set from which processing is to continue. Positioning 
can be in a forward or backward direction and a Key value Cinclud- 
ing a relative record number) or RBA (not for RRDS) can be used to 
identify the logical record at which positioning is set. 


8.11.2.6 CHECK (OS/VS ONLY) 


This macro is used to cause VSAM to determine whether processing of 
a specific asynchronous request has been completed and to suspend 
program execution until processing is completed for an incomplete 
request. CHECK also causes the appropriate active user- written 
exit routine to be entered, if necessary, at the completion of the 
request. 


A test for the completion of an asynchronous request can also be 
made by specifying an ECB in the RPL for the request and testing 
the completion bit. Completion can be tested using the TESTCB macro 
(IO=COMPLETE operand) as well. These two completion tests can he 
used to delay issuing the CHECK macro until the operation is 
completed so that processing is not suspended by the CHECK macro. 


8.11.2.7 ENDREQ 


This macro is used to terminate the processing of a chain of 
requests or a single asynchronous request whose completion is no 
longer required to to free VSAM from keeping track of a position in 
a data set. VSAM can maintain knowledge of the same number of 
positions as the number of requests that can be outstanding concur- 
rently (specified in the ACB or GENCB macro). 
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8.11.2.8 GETIX AND PUTIX (OS/VS ONLY) 


These macros are used to process an index component of a key-se- 
quenced data set (special application). | . a: ogg | 


8.11.2.9 CLOSE 


The CLOSE macro provides the same types of processing functions for 
VSAM data sets as for other types of data sets. It causes VSAM to 
write any unwritten data or index records remaining in the output 
buffers if their contents have changed, update the catalog entry 
for the data set; if necessary (if the location of the end-of-file 
indicator has changed, for example), and write SMF records if SMF 
is being used. The access method control block(s) for the data set 
(such as the ACB's) are restored to what they were before the data 
set was opened and virtual storage that was obtained during OPEN 
processing for additional VSAM control blocks and VSAM routines is 
released. 


Once a VSAM data set has been closed, it must be reopened before 
any additional processing can be performed on it. A CLOSE macro 
With TYPE=T (C(OS/VS) or TCLOSE (DOS/VS) (temporary CLOSE) can be 
issued to cause VSAM to complete any outstanding I/0 operations, 
update the catalog if necessary, and write any required SMF 
records. Processing can continue after a temporary CLOSE without 
the issuing of an OPEN macro. | 


8.11.3 VSAM MACROS FOR SHARED RESOURCES 


This is an interface to VSAM that is designed to be used in a data 
base/data communications environment. Five macros are available. 
Shared resources enable the user to share I/0 buffers, I/70-related 
control blocks, and channel programs among several VSAM data sets 
and permit management of I/70O buffers. The sharing of I/O resources 
and the buffer management available can speed up the direct proces- 
sing of VSAM data sets whose activity is unpredictable and the 
processing of one transaction that requires access to several data 
sets. 7 


8.11.3.1 BLDVRP AND DLVRP 
The BLDVRP and DLVRP macros are provided to build and delete, 


respectively, a shared resource pool. A resource pool can be shared 
by the VSAM data sets being processed in the same partition. 


8.11.3.2 WRIBFR 


The WRIBFR macro causes the writing of a buffer and can be used 
when deferred processing is specified in the ACB. When deferred 
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processing is specified, VSAM does not write a buffer after a PUT 
for direct processing is issued. 


8.11.3.3 SCHBFR AND MRKBFR (OS/VS ONLY) 


The SCHBFR macro is provided to search the shared buffer pool for a 
particular range of RBAs (locate a buffer) and the MRKBFR macro 
causes a buffer to be marked for output without issuing a PUT for 
update. Details regarding the use of these five macros are 
contained in OS/VS Virtual Storage Access Method: Options for 
Advanced Applications. 


8.11.4 CONCURRENT PROCESSING (STRINGS) 


Note that several parts of a VSAM data set can be accessed concur- 
rently via sequential and direct processing by a program or its 
subtasks using the same ACB without the necessity of cleéesing and 
reopening the data set. Each request is processed indépendéntly and 
asynchronously with respect to all other outstanding requests. This 
is called concurrent request processing and is made possible by the 
fact that VSAM can keep account of multiple positions in the data 
set at one time. The number of concurrent requests that can be 
outstanding is specified in the ACB but is extended by VSAM during 
processing if necessary. 


Concurrently outstanding requests for a data set can be any combi- 
nation of sequential and direct processing requests. Each outstand- 
ing request can specify one RPL or a list of RPLs (chained RPLs) 


and synchronous or asynchronous processing (OS/VS only). When a 
request consists of a list of RPLs, the first RPL in the list 
determines whether synchronous or asynchronous processing is 


performed for the request. 


When synchronous processing is requested in the first RPL, control 
is not returned to the user until all requests in the list have 
been processed. When asynchronous processing is specified in the 
first RPL, control is returned to the’user as soon as the chained 
request is accepted by VSAM, and the processing status of the list 
must be checked by the user by issuing a CHECK macro for each RPL 
in the list. 


For additional information about string processing see also page 
191. 3 
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9.0 SYSTEM CONSIDERATIONS 
All storage figures given in this chapter are the best approxima- 


tions available and may differ from user to user. 


9.1 WHERE IS VSAM IN MAIN STORAGE 


9.1.1 ACCESS METHOD SERVICES AND VSAM IN STORAGE (DOS/VS) 


DOS/VS 
Supervisor 
BG/Fn up to 7 program partitions 
User program 
 ‘'SIZE' as 
+ ACBs , RPLS , EXLSTS specified 
in // EXEC 
Space for Record Management areas 
VSAM I/70 buffers and work areas 
Partition VSAM Control Blocks for data sets 
GETVIS- and catalogs 
area 


Access Method Services modules 


CISAM Interface Program modules) 


IK@VRM 


Shareable VSAM modules 


Figure 49. Where is VSAM in storage (DOS/VS) 
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9.1.2 ACCESS METHOD SERVICES AND VSAM IN STORAGE (VS1/7SVS) 


VSAM catalog control blocks 


and appendages SQA 
VSAM routines Capp. 400K) PLPA 
Common 
area 
Butfers 
Data set control blocks 
Access Method Services routines 

Partitions 
Region 

ISAM Interface routines 

VSAM control blocks Fixed LPA 

Nucleus 
area 


Figure 50. Where is VSAM in storage (VS1/SVS) 
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9.1.3 ACCESS METHOD SERVICES AND VSAM IN STORAGE (MVS) 


1200 bytes per opened catalog 
600 bytes per opened KSDS 
300 bytes per opened ESDS/RRDS 


SQA 


VSAM routines (app. 445 K) PLPA 
Common # 


area 


10K per opened catalog 

+ 8K per opened recoverable cat. 
Non-shared res.: 340 bytes/ds. 
GSR: 450 bytes per op. ESDS/RRDS 
 . 900 bytes per opened KSDS 

604 bytes * no. of strings 
Buffers — 


VSAM control blocks (4K) LSQA 
i oo VSAM control blocks, DEBs | Subpool 
— 229/230 


Buffers (non-shared resources) 


CSA 


Access Method Services routines 


Region > | | 
ISAM Interface routines 


| VSAM control blocks Fixed LPA 


Nucleus 
area 


Figure 51. Where is VSAM in storage (MVS) 
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9.2 


er ae 


The 


VSAM WORKING SETS 
1 MINIMUM WORKING SET FOR A SINGLE KSDS (DOS/VS) 


virtual storage requirements of VSAM are big, but it is 


designed to operate efficiently in a VS environment with relatively 
small Real Storage (Working Set) requirements. For further infor- 
mation see the manual 'DOS/VS System Generation’, GC33-5377). 


The 


following conditions are assumed: 


One EXTENT for the data component 


SHAREOPTION(4) not specified (SHAREOPTIONS are described on 


page 95) 


The key is 4 bytes long 


One extent for the sequence set and the index set 


2 data buffers and 1 index buffer (KSDS data set) 
The ACB and RPL are created in this sequence via GENCB, leaving 


the space allocation up to VSAM (ACB, RPL, and GENCB are VSAM 
macros and are described on page 217) | 


The minimum working set for a single VSAM data set (KSDS, ESDS, 
RRDS) can be calculated as follows 


- IK@VRM (VSAM record management) — 22 K!1 


- (if loading/extending the file u kK) 
- Control blocks and channel 
program area uk 


26-30 K + VSAM buffers 
1 per partition or system if in SVA 
If an alternate index is processed as an end-use object, that 


is, without its related base cluster, it is treated as a KSDS 
data set. 


For each _additional data set in the partition, the following 
has to be added to this minimum : 


- Control blocks and channel 
program area 
- VSAM butters 


a 
nN 
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2 


_2.i1.1 WORKING SET FOR ALTERNATE INDEX PROCESSING (DOSZVS ) 


If a path is established between an alternate index and its base 
cluster, the working set requirements for processing the path are 
as follows 


= IKQVRM | 28 K per partition 
= Path entry min. 2K 
= Base cluster min. 4K 


= Other alternate indexes 
in the upgrade set min. 2K per each one 


= Buffers for 
the base cluster, the AIX path and 
each remaining alternate index 
with the UPGRADE | 
attribute belonging to the 
base cluster m K 
(see also section 8.1.5) 


Notes: 


Ths 


All alternate indexes of an upgrade set (except that of the path 
entry) share a common set of buffers whose size is that of the 
largest butfers specified. 


When opening an alternate index and its base cluster through a 
NOUPDATE path, no other alternate index is opened, even if its a 
member of the same upgrade set (parameter NOUPDATE is explained 
on page 110). Therefore, only space for the path entry and the 
base cluster has to be provided unless the base cluster 1s 
opened with NOUPDATE. 


If a base cluster is not processed via a path, but has an 
upgrade set assigned to it, space for the base cluster itself 
and for the upgrade set members Calternate indexes) has to be 
provided. 


Chapter 9. System Considerations. 229 


9.2.2 MINIMUM WORKING SET FOR A SINGLE KSDS (MVS) 


The virtual storage requirements > of VSAM are big, but it is 
designed to operate efficiently in a VS environment with relatively 
small Real Storage (Working Set) requirements. 

The following conditions are assumed: 


e One EXTENT for the data component 


° SHAREOPTION( 4) not specified (SHAREOPTIONS are described on 
page 95) 


e The Key is 4 bytes long 

° One aatenk for the paauenee set and the index set 

° 2 data bukteve and 1 index buffer (KSDS data set) 

° The ACB and RPL are created in this sequence via GENCB, leaving 


the space allocation up to VSAM CACB, RPL, and GENCB are VSAM 
macros and are described on page 217) 


The minimum _working set for a single VSAM data set (KSDS, ESDS, 
RRDS) can be calculated as follows 


- VSAM record management | 36 K1 PLPA 
~ (if loadingvextending the file 12 K) 
- Control blocks and channel 

program area , 4 3.8 K 


39.8-51.8 K + VSAM buffers 
1 PLPA is shared by all regions 


If an alternate index is processed as an end-use object, that is,. 
without its related base cluster, it is treated as a KSDS data set. 


For each additional data set in the region, the following has to be 
added to this minimum 


- Control blocks and channel 
program area 3.8 
- VSAM buffers n 


AN 
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9.2.2.1 WORKING SET FOR ALTERNATE INDEX PROCESSING (MVS) 


If a path is established between an alternate index and its base 
cluster, the working set requirements for processing the path are 
as follows 


1. 


_ VSAM Record management Us K1 PLPA 
- Path entry min. 4 K2 
_ Base cluster min. 3.8 K+ 


= Other alternate indexes 
in the upgrade set min. Yy K2 per each one 


7 Buffers for 
the base cluster, the AIX 
path and each remaining alter- 
nate index with the UPGRADE 
attribute belonging to the 
base cluster m K 
(see also section 8.1.5) 


1 PLPA is shared by all regions 
¢ includes channel program areas 


Notes: 


All alternate indexes of an upgrade set (except that of the path 
entry) share a common set of buffers whose size is that of the 
largest buffers specified. 


When opening an alternate index and its base cluster through a 
NOUPDATE path, no other alternate index is opened, even if its a 
member of the same upgrade set (parameter NOUPDATE is explained 
on page 110). Therefore, only space for the path entry and the 
base cluster has to be provided unless the base cluster 1s 


opened with NOUPDATE. 


If a base cluster is not processed via a path, but has an 
upgrade set assigned to it, space for the base cluster itself 
and for the upgrade set members (alternate indexes) has to be 
provided. | 
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9.2.3 MINIMUM WORKING SET FOR A SINGLE KSDS (SVS) 


The virtual storage requirements of VSAM are big, but it is 
designed to operate efficiently in a VS environment with relatively 
small Real Storage (Working Set) requirements. 

The following conditions are assumed: 


e One EXTENT for the data component 


6 SHAREOPTION(4Y) not specified (SHAREOPTIONS are described on 
page 95) 


° The key is 4 bytes long 

® One extent for the sequence set and the index set 

e 2 data buffers and 1 index buffer (KSDS data set) 

° The ACB and RPL are created in this sequence via GENCB, leaving 


the space allocation up to VSAM C(CACB, RPL, and GENCB are VSAM 
macros and are described on page 217) | 7 


The minimum _working set for a single VSAM data set C(KSDS, ESDS, 
RRDS) can be calculated as follows 


~- VSAM record management 36 K1 PLPA 
- (1i£ loading/fextending the file 12 K ) 
- Control blocks and channel 

program area | 3.3 K 


39.3-51.3 K + VSAM butters 
1 PLPA is shared by all regions 


If an alternate index is processed as an end-use object, that is, 
without its related base cluster, it is treated as a KSDS data set. 


For each additional data set in the region, the following has to be 
added to this minimum 


~ Control blocks and channel 
program area i 3.3 
- VSAM buffers n 


AA 
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9.2.3.1 WORKING SET FOR ALTERNATE INDEX PROCESSING (SVS) 


If a path is established between an alternate index and its base 
cluster, the working set requirements for processing the path are 
as follows 


1. 


~ VSAM Record management Us K1 PLPA 
- Path entry min. 3.4 Ké4 
- Base cluster min. 3.3 K4 


- Other alternate indexes 
in the upgrade set min. 3.4 K* per each one 


= Butfers for 
the base cluster, the AIX 
path and each remaining alter- 
nate index with the UPGRADE 
attribute belonging to the 
base cluster m KK 
(see also section 8.1.5) 


1 PLPA is shared by all regions 
2 includes channel program areas 


Notes: 


All alternate indexes of an upgrade set (except that of the path 
entry) share a common set of buffers whose size is that of the 
largest buffers specified. 3 


When opening an alternate index and its base cluster through a 
NOUPDATE path, no other alternate index is opened, even if its a 
member of the same upgrade set (parameter NOUPDATE is explained 
on page 110). Therefore, only space for the path entry and thea 
base cluster has to be provided unless the base cluster is 
opened with NOUPDATE. 


If a base cluster is not processed via a path, but has an 
upgrade set assigned to it, space for the base cluster itself 
and for the upgrade set members (alternate indexes) has to be 
provided. 
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922.5 MINIMUM WORKING SET FOR A SIN LE KSDS (VS1) : 


The viztual storage requirements of VSAM are big, but it is 
designed to operate efficiently in a VS environment with relatively 
small Real Storage (Working Set) requirements. 

The eo roudnS conditions are assumed: 


° One EXTENT for the data component 


° SHAREOPTION(4) not specified (SHAREOPTIONS are described on 
page 95) | | | 


° The Key ig 4“ bytes long 

e One extent for the sequence set and the index set 

° 2 data buffers and 1 index buffer (KSDS data set) 

e The ACB and RPL are created in this sequence via GENCB, leaving 


the space allocation up to VSAM (ACB, RPL, and GENCB are VSAM 
macros and are described on page 217) | 


The minimum _working set for a single VSAM data set (KSDS, ESDS, 
RRDS} can be calculated as follows : 


- VSAM record management 36 K1 PLPA 

= (if loading/extending the file 12 K) 

- Control blocks and channel | 
program area . 3.3 K 


39.3-51.3 K + VSAM buffers 
1 PLPA is shared by all partitions 


If an alternate index is processed as an end-use object, that is, 
Without its related base cluster, it is treated as a KSDS data set. 


For each additional data set in the region, the following has to be 
added to this minimum : 


- Control blocks and channel 
program area 3.3 
- VSAM buffers n 


aM 
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9.2.4.1 WORKING SET FOR ALTERNATE INDEX PROCESSING (VS1) 


If a path is established between an alternate index and its hbase 
cluster, the working set requirements for processing the path are 
as follows 


Te 


~ VSAM Record management Us K1 PLPA 
- Path entry min. 3.4 K2 
- Base cluster min. 3.3 K2 


= Other alternate indexes 
in the upgrade set min. 3.4 K* per each one 


ae Butfers for 
the base cluster, the AIX 
path and each remaining alter- 
nate index with the UPGRADE 
attribute belonging to the 
base cluster m K 
(see also section 8.1.5) 


1 PLPA is shared by all regions 
2 includes channel program areas 


Notes: 


All alternate indexes of an upgrade set (except that of the path 
entry) share a common set of buffers whose size is that of the 
largest buffers specified. 


When opening an alternate index and its base cluster through a 
NOUPDATE path, no other alternate index is opened, even if its a 
member of the same upgrade set (parameter NOUPDATE is explained 
on page 110). Therefore, only space for the path entry and the 
base cluster has to be provided unless the base cluster is 
opened with NOUPDATE. 


If a base cluster is not processed via a path, but has an 
upgrade set assigned to it, space for the base cluster itself 
and for the upgrade set members (alternate indexes) has to be 
provided. 


Chapter 9. System Considerations 235 


9.2.5 VSAM VIRTUAL STORAGE REQUIREMENTS (DOS/VS) 


Although most of the storage required for VSAM and Access Method 
Services is in SVA, additional virtual storage is required in the 
user's address space for control blocks, buffers, Access Method 
Services, and if used, the ISAM interface routines. | 


The following information is based on DOS/VS'7 Release 34. For 
further information see DOS/VS2 System Generation, GC33-5377-6. 


° Access Method Services 
Any function except BLDINDEX, EXPORTRA, RESETCAT. = 116K-166K 
BLDINDEX (without internal sort area) = 138K 
EXPORTRA = &Y14UK 
RESETCAT = 238K 

@ Main storage requirements per opened catalog 
Catalog with 3K buffer (nonrecoverable on 3330) = 10K 
Catalog with 8K buffer (nonrecoverable on 3330) = 18K 
Catalog with 3K buffer (recoverable on 3330) = 14K 
Catalog with 8K buffer (recoverable on 3330) = 23K 

2 Catalog management control blocks (£f0r catalog access) 
OPEN/CLOSE | = 1K 
LOCATE, UPDATE, DEFINE NONVSAM, DELETE SPACE, 
DELETE catalog, LISTCAT | rs 5K 
DEFINE (common) = 6-7K. 
DEFINE catalog, ALTER = 145 

e Record management control blocks Cexample) 
This is an example for a KSDS data set: 
1. Key length is 8 
2. Number of data buffers is 2 (2048) 
3. Number of index buffer is 1 (512) 
4. No IMBED, no KEYRANGES 
5. Disk is IBM 3330 
Total amount used for control blocks = 4 kK bytes 
Total amount used for buffers (2*2048+1*512) = 4608 bytes 


236 VSAM PRIMER and REFERENCE 


9.2.6 VSAM VIRTUAL STORAGE REQSUTREMENTS (MVS) 


Although most of the storage required for VSAM and Access Metkeod 
Services is in the PLPA, additional virtual storage is required in 
the user's address space for control blocks, buffers, Access Method 
Services, and if used, the ISAM interface routines. 


The following information is based on VS2 Release 3.7. For further 
information see OS/VS2 Storage Estimates, GC28-060H4-4. 


e Access Method Services 
Any function except BLDINDEX, EXPORTRA, RESETCAT = 220K 
BLDINDEX (without internal sort area) = 170K 
EXPORTRA = 4WUSK 
RESETCAT = 270K 

° Main storage requirements per opened catalog 

CSA + SOA 

Catalog with 3K buffer (nonrecoverable on 3330) = 10K 1K 
Catalog with 8K buffer (nonrecoverable on 3330) = 18K 1K 
Catalog with 3K buffer (recoverable on 3330) = 18K 1K 
Catalog with 8K buffer (recoverable on 3330) = 24K 1K 
VSAM LS@A requirement = Uk 

° Catalog management control blocks (for catalog access) 
OPEN/CLOSE = 1K 
LOCATE, UPDATE, DEFINE NONVSAM, DELETE SPACE, 
DELETE catalog, LISTCAT = 5K 
DEFINE (common) = 6-7K 
DEFINE catalog, ALTER = 14K 

© Record management control blocks (Cexample) 
This is an example for a KSDS data set: 
1. Key length is 8 
2. Number of data buffers is 2 (2048) 
3. Number of index buffer is 1 (512) 
4. No IMBED, no KEYRANGES : 
5. Disk is IBM 3330 
Total amount used for control blocks = 5 K bytes 
Total amount used for buffers (2*2048+1*512) = 4608 bytes 
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9.2.7 VSAM VIRTUAL STORAGE REQUIREMENTS (SVS) 


Although most of the storage required for VSAM and Access Method 
Services is in the PLPA, additional virtual storage is required in 
the user's address space for control blocks, buffers, Access Method 
Services, and if used, the ISAM interface routines. 


The following information is based on VS2 Release 1.7 with VSAM 
ICR. For further information see OS/VS2 SVS Independent Component: 
Planning for Enhanced VSAM, GC26-3869. 


o. Access Method Services 

Any function except BLDINDEX, EXPORTRA, RESETCAT = 204K 

BLDINDEX (without internal sort area) = 204K 

EXPORTRA = 444K 

RESETCAT = 390K 
° Main storage requirements per opened catalog 

Catalog with 3K buffer (nonrecoverable on 3330) = 10K 

Catalog with 8K buffer (nonrecoverable on 3330) = 18K 

Catalog With 3K buffer (recoverable on 3330) . = 14K 

Catalog with 8K buffer (recoverable on 3330) = 23K 
° Catalog management control blocks (for catalog access) 

OPEN/CLOSE | | = 1K 

LOCATE, UPDATE, DEFINE NONVSAM,DELETE SPACE, 

DELETE catalog, LISTCAT | = 5K 

DEFINE (common) = 6-7K 

DEFINE catalog, ALTER = 4K 
° Record management control blocks (example) 

This is an example for a KSDS data set: 

1. Key length is 8 

2. Number of data buffers is 2 (2048) 

3. Number of index buffer is 1 (512) 

4. No IMBED, no KEYRANGES 

5. Disk is IBM 3330 

Total amount used for control blocks = 5 kK bytes 

Total amount used for buffers (2*2048+1*512) __= 4608 bytes 
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9.2.8 VSAM VIRTUAL STORAGE REQUIREMENTS (VS1) 


Although most of the storage required for VSAM and Access Method 
Services is in the PLPA, additional virtual storage is required in 
the user's address space for control blocks, buffers, Access Method 
Services, and if used, the ISAM interface routines. 


The following information is based on VS1 Release 6. For further 
information see OS/VS1 Storage Estimates, GC24-5094-6. 


° Access Method Services 
Any function except BLDINDEX, EXPORTRA, RESETCAT = 220K 
BLDINDEX (without internal sort area) = 170K 
EXPORTRA = 4YU5K 
RESETCAT = 270K 
e Main storage requirements per opened catalog 
Catalog with 3K butfer (nonrecoverable on 3330) = 10K 
Catalog with 8K butfer (nonrecoverable on 3330) = 18K 
Catalog with 3K buffer (recoverable on 3330) = 14K 
Catalog with 8K buffer (recoverable on 3330) = 23K 
° Catalog management control blocks (for catalog access) 
OPEN/CLOSE | = 1K 
LOCATE, UPDATE, DEFINE NONVSAM,DELETE SPACE, 
DELETE catalog, LISTCAT = 5K 
DEFINE (common) = 6-7K 
DEFINE catalog, ALTER = 14K 
e Record management control blocks (example) 
This 1s an example for a KSDS data set: 
1. Key length is 8 
2. Number of data butfers is 2 (2048) 
3. Number of index buffer is 1 (512) 
4. No IMBED, no KEYRANGES 
5. Disk is IBM 3330 
Total amount used for control blocks = 4 K bytes 
Total amount used for buffers (2*20484+1*512). = 4608 bytes 
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A.9 APPENDIX A. VSAM CATALOG MISCELLANEOUS 


A.1 VSAM CATALOG KEYRANGES 


A.1.1 THE HIGH-KEYRANGE (CHKR) 


As described in the previous section, each VSAM catalog is a 
KEYRANGE data set (normal Keyranges are described on page 91). The 
second Keyrange called the ‘High-Keyrange’ (HKR) or the ‘True Name 
Section’ is where the actual data set names, volume names, etc. 
reside (Keyrange X'4¥0' —- X'FF!). | 

Each CI here is 512 bytes (the same as throughout the data and 
index components of the catalog) and contains 44 byte data set 
names and 3 byte LKR CI pointers. Each LKR CI pointer associated 
With each data set entry contains the number of a CI in the 
Low-~Keyrange (LKR) (see section A.1.2) where the actual data and 
information with regard to the particular entry itself resides. 
Thus the HKR functions as an additional index to the LKR record. 


Given a data set name the index component is searched to find the 
entry in the HKR. Once there, Catalog Management can pick up the 
LKR CI pointer multiply it by 512 (CI size) to get the RBA value, 
add it to the beginning of the LKR extent, and find the actual data 
relative to the data set name. 


Catalog Management uses regular Keyed direct VSAM Record Management 
processing to do I/0 to the HKR. The HKR is subject to CI and CA 
splits Cunlike the LKR) and therefore the catalog should be subject 
to periodic reorganization by the user. 


A.1.2 THE LOW-KEYRANGE (CLKR) 


The LKR is actually the first extent of the VSAM catalog data space 
(Keyrange xX'‘'00' = SSE *). It is where the body of information 
relating to data sets is stored. It consists of a series of 
pre-formatted 512 byte data CIs each of which contain the appropri- 
ate data set, volume, etc., information. 

An entire 512 byte CI is wholly used to contain a catalog entry (it 
there is not enough room available, extension records are built:. 
A KSDS cluster, for example occupies three 512 byte CIs (cluster, 
data and index entry). 


‘The Catalog Self Describing Records (see next section A.1.4) reside 
in the first 15-20 (dependent on device type) CIs of the LKR. 
Catalog Management when it is opening the catalog accesses these 
records via its own channel program and builds the catalog control 
blocks needed. Control Interval processing (CNV) (see description 
on page 74) is used to do I/0 to the rest of the LKR. Since CNV 
processing is done to a series of preformatted CIs, the LKR is not 
subject to CI and CA splits. 
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If a record needs to be retrieved, it can be done via the CI 
pointer retrieved from the HER. If a record needs to be written, 
it is first written in the LKR. Then the appropriate HKR record 
pointing to it is written. a. 


R.1.3 CATLOG HKR AND LKR LOGIC 


As described in the previous sections, the catalog consists of 3 
parts, the index, the HKR and the LKR. The index points to the HKR 
and the HKR points to the LKR (see figure 52). The HKR is used 
like a second index. 3 | 


This structure was chosen for the following reasons: 


1. As shown in figure 52, some records in the LKR contain CI number 
pointers pointing to each other. Due to these pointers, CI or CA 
splits are not allowed, since otherwise all pointers must be 
rewritten after a split. 

2. KSDS allows direct access using an index to find a specific 
entry, so the advantages of a KSDS were included. 


Since an ESDS structure (LKR) does not have an index and a KSDS 
data component allows splits, both these functions have been 
combined using a HKR where splits are allowed. Record Management 
routines are used to access the HKR via the index. Catalog Manage- 
INREent routines convert the LKR CI pointer in the HKR record (via its 
own channel programs). | 


Preformatting: The catalog areas are preformatted in the different 
systems at different times (preformatting can take a considerable 
amount of time depending on the size of the catalog): 


e MVS all catalog primary allocation space is prefor- 
matted when first entry is stored in catalog. 
° DOS/VS,VS1,SVS one CA is preformatted the others when needed. 


A.1.4 THE SELF DESCRIBING RECORDS 
Each VSAM data set must be cataloged in a VSAM catalog. All the 


information with regard to the VSAM data set needed for open, 
close, EOV, allocation, etc, is Kept in a VSAM catalog. 


A VSAM catalog being a special KSDS, must be cataloged somewhere. 
One cannot 'catalog' a catalog. What is used instead are self-des- 
¢cribing records in each catalog. These records describe the 
catalog itself, exactly like a catalog would describe a VSAM data 
set. 


These records (described in the appropriate VSAM or Catalog Manage- 
ment PLMs) reside in the first few CIs of the LKR. They describe 
the space the catalog resides in, its extent per each Keyranc:a. 
where the free records are, what type of device the catalog resid:s 
on, etc. If these records are bad, then the catalog is bad and the 
message "Catalog Unavailable” is issued. 
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Figure 52 shows the relation of catalog entries (records) fora 
KSDS cluster ‘PAYROL' with its data component 'PAYROL.D' and its 
index component 'PAYROL.I'. All CIs are 512 bytes in length. The 
index CIs have been shortened due to limited space. 
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C = Cluster entry HKR = High Keyrange 

DB = Data component entry LKR = Low Keyrange 

I = Index component entry IS = Index Set 

*+ = variable length ISS = Index Sequence set 

* = Miscellaneous fields (see PLM) 

| 


= these fields contain CRA references (recoverable catalog only) 


Figure 52. VSAM catalog structure 
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A.2 TIMESTAMPS, VTOC — 


The VSAM catalog records five different timestamps. The most. 


important and the only one discussed in this manual is the ‘volume 
timestamp’ (most other timestamps are used internally for identifi- 
cation). | | 3 : 


A.2.,1 VOLUME TIMESTAMP 


The purpose of this timestamp is to check that the catalog and its 
owned volumes are on the same level from the space allocation 
standpoint. 


This timestamp is located in the Format 4 DSCB (see page 245, note 
6) as well as in the volume record (see page 159). 


Actually, this timestamp is recorded twice in the Format-H, at 
offset X'4C' (page 245 note 3) as well as at X'57'(€see page 245 
note 6). The former one (Cat X'4C') is used by Version 1 VSAM and 


IEHDASDR; it is completely ignored by the checking algorithm in 


Enhanced VSAM. 


The volume timestamp update is treated differently for a recovera- 
ble catalog as compared to nonrecoverable catalog. In a recovera- 
ble catalog, when space on a volume is altered the first time after 
the CRA is opened, the timestamp in the Format 4. DSCB and the 
volume record in the VSAM catalog will be updated. Subsequent 
alteration in VSAM data space will not cause the volume timestamp 
to be updated. Any allocation change ina data space (DEFINE or 
DELETE), which changes the space bit map (this is a field in the 
volume record where VSAM records which VSAM data space tracks are 
free or occupied) changes the volume timestamp (nonrecoverable 
catalog only). | 


The volume timestamp checking algorithm in Enhanced VSAM is differ- 
ent from Version 1. In Version 1 VSAM the old timestamp field in 
the F4 DSCB (CX'4C' - X'53) was checked against the catalog volume 
timestamp (see page 159) for equal or high. In Enhanced VSAM, the 
check is for exact equal at volume mount time. A mismatch will 
cause the UCBAMV bit not to be set. If there is no mismatch, this 
bit will be set ON ('1') by VSAM. This indicatoxr will be checked 
by VSAM OPEN. a 


A timestamp mismatch can be encountered in VSAM usage and will 


cause serious operational problems. This out-of-syne condition is 


usually caused by restoring a back-level volume or catalog. 
Timestamp mismatch will prevent opening of all VSAM data set on 
that volume. | 


On page 254 the timestamp mismatch problem is discussed in more 
detail. | | 
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A.2.2 NTOC Fil AND F4 DSCB'S (LABELS) 


The following is part of a printout of the VTOC taken after the 
LISTCAT ALL example (see section 7.9.2 on page 142). 


DOS/VS example (Cinput): OS/VS example Cinput): 
//7PRIMER JOB WTSC,IBM,MSGLEVEL=1 

// JOB VTOC : //PRIMOLI2 EXEC PGM=IEHLIST 
/7 ASSGN SYS004,X'191' //7SYSPRINT DD SYSOUT=A 
7/7 ASSGN SYS005,X'00E' //0D1 DD UNIT=3330,DISP=OLD, VOL=SER=WTVSAM 
// PAUSE REPLY NO IF MSG 8V96D IS ISSUED //SYSIN DD * 
//7 EXEC LVTOC LISTVTOC DUMP, VOL=3330=WTVSAM 
/& /* 


The output format has been modified to fit on this paper size. 


CONTENTS OF VTOC ON VOL WTVSAM 


Once 6 @ ves ee we ee DO ee Se IG ew 6 AD eS eo ce we BSE ee: 24ST Se vw 
GG se ee WO Se. & we, BOE we Se SBD we SS we 464 2s SL TW. eS oe TD ews a BR SS ae BF ee ID see 
99... - 104... .:109.2.2~.114...319~. 7 74129. . «. «134... «2139 DSCB ADDR (CCHHR) 


1. Format 4 DSCB (VTOC descriptor): 


FORMAT 4 DSCB 


0404040404040404040404040404040404040404040/ /04040404040404040404040404040404 
F4000000030502450194000E007708010000019B00133/ /00271C8BDE7F 9BAS1F 90008000378BDE 7F IBA51F 900000000000 


—— oa aE FEE EEE EF Eee ttt 
2 3 4 5 6 


000000000000010000000003000000110000000000000/ /000000000000000000000000 0000000301 


2. Format 1 DSCB (VSAM catalog): , 


29999994 ..VSAMDSPC. TSBDE7F4.TAFAZAB8 


FLE6E3E5E2C1D400014D016363016D010000C9C2D4GD6E/ /4040000000000000000008C0001000000000000010C000000100 


8 9 10 
00003360D0000810000010000000300120000000000000/ /000000000000000000000000 000000030% 


3. Format 1 DSCB (VSAM data space): 


29999992 .VSAMDSPC. T8BDE7F5.TOC9DD 78 


11 
FIE6E3E5E2C10400014D016363016D010000C9C2D4D6E/ /4040000000000000000008C0001000000000000010C000000200 


12 13 14 
0000336D0000810000040000006700120000000000000/ /000000000000000000000000 0000000304 


The numbers are explained on the next page. 
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Legend: 


W & 


10 


11 


12 
13 


14 
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H oO 


This line was added by the utility program to identify the 

Format-4 DSCB (Label). | 7 

Format-4 identifier | 

bytes 76-83 (X'4Cc'-'53').. 

"VSAM old timestamp’ used by Non-Enhanced VSAM and IEHDASDR. 

This timestamp is updated but not checked in systems using 

Enhanced VSAM (DOS/VS 2R.31, MVS 2R.3.6, SVS with ICR, VS1 

2R.4). 

Byte 84 (X'54"') bit QO. | 

"VSAM ownership bit'. This volume is owned by a VSAM catalog. 

Whenever a VSAM catalog is defined or a VSAM catalog allo- 

cates space on a volume, bit '0'" is set ON. 

bytes 85-86 (X'55’'-'56'). | 7 

Start of CRA (track offset in hex). 0037 = cyl 2 track 17 

(dec). 

bytes 87-94 (X'57-'S5E'). 

"VSAM volume timestamp’. This is the  catalogq/volume times-— 

xamp. 

bytes 0-43 (X'OO'-'2B'). 

This is the identification of the VSAM catalog: 

Z9999994 = the '4' at the end identifies this VSAM object as 
a VSAM catalog. In DOS/VS, SVS and VS1 this is the 
identification for a user catalog (¢( the master 
catalog uses a '6' instead of a '4'). In MVS the 
master and user catalog identifier is ‘4Y". 

TXKKRHKKKH.TKRKKKXKK 
is the timestamp when this F-1 DSCB (Label) was 
created. 

Byte 44H (X'2C'). 

Format-1 identifier 

bytes 82-83 (XK'52'-'53'). 

Data set organization (0008 = VSAM) 

Byte 93 (X'S5D') bit 3. 

"Data set security bit' Cin OS/VS systems also ‘'OS/VS pass- 

word protection bit'). This bit prevents other access 

methods from accessing this data space. | 
bytes 0-43 (X'O00'-'2B'). 

This is the identification of a VSAM data space: 

Z9999992 = the '2' at the end identifies this VSAM object as 
a suballocatable VSAM data space. 

Byte 4&4 (X'2c'). 

Format-1 identifier 

bytes 82-83 (X'52'-'53'). 

Data set organization (0008 = VSAM) 

Byte 93 (X'5D') bit 3. | 

‘Data set security bit’ (Cin OS/VS systems also ‘'OS/VS pass- 

word protection bit'). 

This bit prevents other access methods from accessing this 

data space. | 
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A.3 HOW TO CALCULATE USED SPACE IN A VSAM CATALOG 


As described in section 7.4 on page 102 the space for a catalog can 
be calculated using the worksheet of the Access Method Services 
manual. Sometimes, however it might be necessary to calculate the 
used space ina catalog as a base for defining a new catalog. 


Normally the statistics ‘fields show the number of records or used 
RBA-~values, but for a catalog these fields in a LISTCAT output of a 
catalog are meaningless and cannot be used for space calculations. 


The only possible way to find the number of occupied records (CIs) 
in the catalog 'Low-Keyrange' area (usually about 90% of the 
catalog space), is to analyze the catalog control record, CCR (see 
also VSAM Logic manuals). | | 


The following is an example of how to print the CCR-record of a 
catalog to estimate the used space. 


The format of the important CCR-record fields is: 


X'OO'-"Z2B'= Key C44 bytes) 

X'O1'-'O3'= 3, the CI number of this record 

x'2C' = X'D3° = 'L' Cid of CCR record) 

X'2D'-"2F'= Codnumber of highest CI in the extent 

X'30'-'32'= Cbh)number of next free CI (not previously assigned) CI 


X'33'-'35'= Cadnumber of deleted (previously assigned but freed 
by deletion) CIs (they need not to be contiguous) 


The approximate catalog size can be estimated by calculating the 
number of CIs used in the catalog Low-Keyrange, which is about 90% 
of the actual catalog size, using this formula: 


Catalog Low-Keyrange = b- a + 1 


The following is a graphic to show how the values ‘a’ - "c* are 
used. | 
, 
fn 


total number of allocated CIs (LKR) 
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The CCR is the fourth CI record of any catalog and can be printed 
uSing Access Method Services commands as follows: 


DOS/VS example (input): OS/VS example (input): 
// JOB PRINT UCAT (PARTIAL) 7/PRIMER JOB WTSC,IBM,MSGLEVEL=1 
// DLBL UCAT, 'PRIMER.UCATL',,VSAM /7PRIMO562 EXEC PGM=IDCAMS 
77 EXTENT SYS010,WTVSAM //STEPCAT DD DSN=PRIMER.UCAT1,DISP=SHR 
7/7 ASSGN SYS010,DISK,VOL=WTVSAM, SHR //UCAT DD DSN=PRIMER.UCAT1 ,DISP=OLD 
7/7 EXEC IDCAMS, SIZE=AUTO //SYSPRINT DD SYSOUT=A 
PRINT INFILE (UCAT) - //SYSIN DD * 

SKIP (3) - PRINT INFILE (UCAT/UCATMRPH) = - 

COUNT (1) SKIP (3) , < 
/& COUNT (1) 

/* : 


Output of Access Method Services (DOS/VS and OS/VS are similar): 


LISTING OF DS -PRIMER.UCAT1 


KEY OF RECORD - 00000003000000000000000000000000000000000000000000000000000000000000000000000000000// 


0000 60000003 00000000 00000000 00000000 00000000 00000000 00000000 G0G00000 *............. oe ware Sie / 
0020 00000000 00000000 00000000 D30001SF 00018D00 01660001 72000318 00000320 %.......... be ee eee HV 
0040 00000320 00000322 00000370 00000370 00000002 00000078 0000008C O0000008C %......... cece cece ee A 
0060 O000008E 0000008E 00000000 00000000 00000000 00000000 00000000 o0000000 *........ eS eee ee // } 
0080 00000000 00000000 00000000 00000000 00000000 00000000 00000000 D0000000 *............ er / ‘ 
OOAD 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *............ (ee awacss f/ 
00CO 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 x...... ele eig elena Bere ere is // 
OOEO 00000000 00000000 00000000 00000000 00000000 o0000000 00000000 co0000OO *........... heseesanLl 7S 
0100 00000000 00000000 00000000 00000000 00000000 00000000 O0000000 DODDDNND HK... ce wee ewer cee nnee Cf 
6120 90000000 00000000 00000000 00000000 00000000 00000000 00000000 OOD000D0D *%...... 1... ee eee eee // 
0140 00000000 00000000 00000000 00000000 00000000 00000000 00000000 DOODD0N0D %.. 1... ce ee eee ee ee oe we 
0160 00000000 00000000 00000000 00000000 00000000 00000000 00000000 o0000000 *........ ESS 0 WS wie B« it 
0180 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *..............e eens “7 
O1A0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 OOODOONO *.... 1... eee ee ee ee le : 
01C0 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 *..... errr eee eee Af \ 


O1EO 00000000 00000000 00000000 00000000 00000000 00000000 00 ee ee ee ee ee ee eee of 


IDCO005I NUMBER OF RECORDS PROCESSED WAS 1 
IDCOOO1I FUNCTION COMPL, HIGHEST COND.CODE WAS 0 


IDC0002T IDCAMS PROC COMPL. MAX. COND.CODE WAS 0 


Note: The output lines were truncated on the right side due to 
limited page size. 


—~ 
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The approximate catalog size can now be calculated by adding the 
three logical parts: 


e Low-Keyrange 


The number of occupied CIs in 'Low-Keyrange' is 40, since: 


b- at 1 = X'18D' - X'166" = X'27' + 41 = 4O 
Each CI is 512 bytes in length. Use the device characteristics 
table in section 8.2 on page 196 to determine the number of 


tracks: 


device type = 3330 = 20 * 512 bytes per track 


UO entries = 2 tracks for data in Low-Keyrange used 


Add 1 track per data CA (for the imbedded sequence set record). 


The data CA sizes in a catalog are as follows: 


2305, 3330, 3350 
2314, 3340 


3 tracks (2 tracks + 1 track sequence set) 
5 tracks (4 tracks + 1 track sequence set) 


The allocation units in a catalog are one data control area + one 
track. 


Total space used for Low-Keyrange = 3 tracks 


e High-Keyrange 
The High-Keyrange size is about 10% (DOS/VS Rel.34 20%) of 
Low-Keyrange (minimum 1 allocation unit). 

e Index set 


The index set size is 1 allocation unit Can allocation unit is 
1 CA (3 or 5 tracks depending on device type) + 1 track). 


Total calculation summary for the catalog: 


- Low-Keyrange = 3 tracks 
-~ High-Keyrange = 3 tracks 
- index set = 3 tracks 
Total catalog space used = 9 tracks 
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A.4Y CATALOG RECOVERY 


A.4. 1 INTRODUCTION 


Unlike nonVSAM, each VSAM data set must be cataloged in a VSAM 
catalog. In order to process a VSAM data set, that data set's 
catalog entry must be accessible. A damaged catalog will prevent 
accessibility of VSAM data sets even though the data may be in 
perfectly good condition. | 


In an MVS environment, a damaged catalog can also affect nonvVSAM 
users. It is not uncommon to find an MVS installation having a 
VSAM catalog that contains several thousand nonVSAM entries. 
Damage to such a catalog does not normally prevent accessibility of 
nonVSAM data sets, however, the changes that have to be made in JCL 
procedures and VS2 TSO C-lists may impact the operation of an 
installation. 


A much more common problem than the damaged catalog 1s an 
out-of-syne condition where the catalog or its owned volumes is 
down-level. A down-level situation is usually created by restoring 
an earlier version of the catalog or its owned volumes (see also 
description of DUMP/RESTORE on page 255). 


Such out-of-syne conditions will usually prevent opening of the 
VSAM data set on that particulhr volume. For all practical purpos- 
es, this condition is just as unacceptable as the damaged catalog 
as far as the particular application is concerned. 


With Enhanced VSAM a recovery facility is available for VSAM 
catalogs. It enables VSAM data sets and catalog entries for both 
VSAM and nonVSAM data sets to be recovered in the event that a VSAM 
catalog cannot be read for any reason. Use of the recovery facili- 
ty for a VSAM catalog is specified via the RECOVERABLE attribute. 
Use of this facility is optional. | 


When a catalog is recoverable, catalog information for each data 
set described by the catalog is recorded in both the catalog and 
usually in the catalog recovery area (CRA) on the first volume of 
the data set on which a data space is defined. Thus, each volume 
identified by a recoverable catalog gontains its own catalog 
recovery information. | | 


A CRA is automatically reserved on a volume by VSAM when the first 


data space allocation occurs for the volume. | Initially, one 
cylinder is allocated. I£ this’ space becomes filled, one addition- 
al cylinder is allocated each time a cylinder is filled. A CRA can 


contain a maximum of 16 cylinders. 


The location of the CRA is specified in the Format-4 DSCB (Label) 
for the volume and is not indicated in the associated catalog (see 
page 49 and 245). Whenever an entry in a recoverable catalog is 
updated, the corresponding catalog information in the catalog 
recovery area of the affected volume is also automatically updated. 
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This means the affected volume must be mounted. 


In DOS/VS systems if the first data space on a volume is a catalog 
With no DATA or INDEX parameter specified, the CRA is not suballo- 
cated from the data space. Therefore, the space value specified in 
the EXTENT control statement must be increased by 1 cylinder for 
the CRA. 


In OS/VS systems if the first data space on a volume iS a unique 
data space the CRA is not suballocated from the data space. The 
OS/VS DADSM routines try to dynamically allocate one additional 
cylinder for the CRA. For catalogs, the CRA is always suballocated 
from the catalog data space. 


If the catalog is down-level, a current copy of the entries are 
still available through the CRA. On the other hand, if the volume 
is down-level (Cand, therefore, also the data set and the CRA), the 
data and the associated catalog entries can be unloaded Cusing the 
CRA) and reloaded back into the catalog. This will synchronize the 
catalog with its owned volumes. 


Two points are worth noting: 


1. The CRA, although containing duplicated records of the catalog, 
cannot be processed as a catalog. 


2. With Enhanced VSAM, the synchronization of the catalog with its 
owned  volume(s) will require data movement via the 
EXPORTRA/IMPORTRA commands (described later). 


With DOS/VS Release 33, MVS Data Management Selectable Unit, SVS 
With VSAM ICR, and VS/1 Release 6a new Access Method Services 


command, RESETCAT, 1s introduced. This command will take the 
entries in the CRA and use them to update (insert, delete, replace) 
the catalog. This synchronization process does not require data 


movement, thus providing a faster way to recover the catalog than 
EXPORTRA/IMPORTRA. 


In DOS/VS nonVSAM data sets cannot be defined in a recoverable 
catalog. 


A.4.2 CRA OPEN AND CLOSE 


A CRA is opened when it is first needed (when CRA records have to 
be changed, added or deleted), and will remain open as long as the 
user catalog is open. Because of this fact, the CRA volume must 
remain mounted during that period of time Cuntil the user catalog 
is closed). 


The CRA is not referenced when the catalog is read. 
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A.4.3 RECOVERABLE OR NONRECOVERABLE CATALOG © 


A.4.3.1 MASTER CATALOG 


It is the consensus today that the master catalog should be kept 
‘pure’. In other words, the master catalog should contain only the 
following Kinds of data set entries: 


° User catalog connector entries 


Additional entries for MVS systems only: 

e ALIAS entries 

° CVOL connectors and ALIASes 

° System data sets such as LINKLIB 

° System work data sets such as Page Space 


The only way that a master catalog can be kept ‘pure’ and not be 
cluttered with user data sets is through the implementation of a 
VSAM password at the update level (see description on page 52). 


With a ‘pure’ master catalog established, the only advantage that 
we can conceive in using a recoverable catalog is the facility of 
EXPORTRA ENTRIES. This may be useful ina VS2 TSO environment 
where it is not unusual to find hundreds of ALIASes (userid) 
relating to the user catalog. The EXPORTRA/IMPORTRA command will 
allow us to back up and restore all the entries ina straightfor- 
ward manner. 


A.4.3.2 USER CATALOG 


For the user catalog, the selection of recoverable versus nonrecov- 
erable is not as clear-cut. Before a user catalog is defined, the 
following questions should be addressed: 


1. Is recovery of the catalog an important issue? 


It is conceivable that VSAM data sets are used for temporary 
files, which minimize the importance of catalog recovery. 


2. Is good catalog performance important to the installation or 
application? : 


The catalog to be used for VS2 TSO data sets may want to consid- 
er nonrecoverable for performance reasons. Performance tests 
have shown that defining a KSDS took considerably longer with a 
recoverable than a nonrecoverable catalog. 
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3. Are the missing Access Method Services functions for a recovera- 
ble catalog important to the installation? 


The following functions are (partially) implemented for recover- 
able catalog: | 


Nonrecoverable Recoverable 
UNLOAD/RELOAD via REPRO’™ yes partially supported 
DELETE NOSCRATCH®é yes no 
Catalog to catalog copy? yes no 


Legend: 


1 Unload/reload of a recoverable catalog via REPRO will work 
except that the CRA will be ignored in both directions. 


¢ These commands are supported in MVS only. 


UW. Are the added functions in EXPORTRA, IMPORTRA and RESETCAT 
playing a role in selecting recoverable catalog? 


We are referring to features that are not directly related to 
recoverability. An example of this is EXPORTRA allowing you to 
unload a nonVSAM entry and all its associated ALIASes, whereas 
EXPORT does not support nonVSAM data sets. 
The most important question to raise is the first one. If recovery 
of the catalog and synchronization of the catalog with its owned 


volumes are germane to the operation of the installation, then 
recoverable catalog is the only way to go. 


5 «= CATALOG BACKUP 


Generally, there are two ways to backup a VSAM catalog: 
1. Unload/7reload the catalog usSing REPRO 
2. Dump the catalog volume with utilities: 
° DOS/VS: BACKUP/RESTORE (see utilities manual GC33-5381) 
° OS/YS + ITEHDASDR (see utilities manual GC26-3901 (VS1) or 


GC26-3902 (VS2)) 
DRWDASDR (Program Product 5740-UT1) 
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A.5.1 REPRO (CATALOG UNLOAD/RELOAD) 


REPRO can be used to unload and reload a VSAM catalog. The unload- 
ed version called portable catalog here, can be reloaded back into 
an existing or new catalog. The new catalog must 


e have the same name, same devicetype, same volume serial number 
as the catalog prior to unload. 


e be large enough in its primary allocation to accommodate all 
the extents of the portable catalog. 


Insertion, deletion, and replacement will take place for the target 
catalog. The content of the target catalog after reload will have 
the same content as the portable catalog with one exception; when 
reloading into a new catalog, the volume record of the tardert 
catalog's volume is retained. 


Unload/reload will ignore the CRA in both directions and essential- 
ly will treat recoverable and nonrecoverable catalogs alike. When 
reloading into a new recoverable catalog, the CRA which is empty 
except for self-defining records, will be out of step with the 
catalog. RESETCAT should be executed immediately after reload is 
performed (since RESETCAT deletes all entries associated with the 
catalog volume, all data sets on the catalog volume should be saved 
With EXPORTRA before the RELOAD CATALOG operation is started). 


In addition to 1lgnoring the CRA, reload will not attempt to 
synchronize the Format-4 ‘volume timestamp' and the catalog 'volume 
timestamp’ (see section A.2 on page 244). 


This will create an out-of-syne condition that will preclude the 
opening of VSAM data sets on the catalog volume. 


If the catalog is to be opened as a data set, as in the cases of 
LISTCRA COMPARE and RESETCAT, VSAM OPEN will ‘fail with a volume 
timestamp mismatch. The only way to get around the problem is to 
SUPERZAP the Format-4 ‘volume timestamp’ timestamp (see page 245 
note 6) (for DOS/VS systems use IKQVDU, see description on page 
179; for OS/VS systems use H/AMASPZAP, see description on page 
270). 


This superzapping undoubtedly is a violation of VSAM integrity, but 
if the action is confined to LISTCRA and RESETCAT, there should be 
no unpredictable and undesirable results. It should be pointed out 
that the above discussion is applicable only to the catalog volume. 
Timestamp out-of-syne condition on a catalog volume without a 
catalog will be corrected by RESETCAT. 
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Even with the restrictions of not updating the CRA and F4UDSCB, any 
out-of-syne condition can be corrected by RESETCAT. Therefore, 
unload/reload is a viable method in catalog backup and restore 
(Since RESETCAT deletes all entries associated with the catalog 
volume, all data sets on the catalog volume should be saved with 
EXPORTRA before the RELOAD CATALOG operation is started) or backup 
With catalog. 


One final point regarding reload: if LISTCAT ALL is executed in 
the same job step as reload, probably only a part of the catalog is 
listed since the catalog has not yet been closed. 


Examples on how to use REPRO for catalog unload/reload are included 
on pages 171, 172. 


A.5.2 DUMP/RESTORE (OS/VS UTILITY) 


A.5.2.1 DUMP/RESTORE VOLUMES (OS/VS) 


ITEHDASDR dump obviously will take more time than unload, especially 
on a device such as 3350. 3850 users should also be aware thac 
3330V (which is a virtual 3330) is an unsupported device 9 
ITEHDASDR. 


ITEHDASDR restore has the distinct advantage of providing the same 
level of FHDSCB and CRA as expected by VSAM catalog management. On 
the other hand, IEHDASDR will restore all data sets to an earlier 
level which may not be acceptable. Furthermore, the time involved 
in restoring a pack may be prohibitive in urgent recovery situa- 
tions. Its shortcoming may outweigh its advantages. 


As VSAM objects are protected against any nonVSAM access method by 
setting the "data set security bit’ ('OS/VS password protection 
bit') in the F1-DSCB (Label) X'5D' to 'ON' Cnot to be mixed up with 
VSAM password protection, which is stored in the VSAM catalog 
only), special setup is necessary for volumes containing VSAM 
objects when using IEHDASDR or DRWDASDR (PP 5740-UT1) (see the 
appropriate manuals). 
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The following are examples on how to use IEHDASDR: 


The first jobs dumps the volume WTVSAM. This job was executed after 
the LISTCAT ALL example (see section 7.9.2 on page 142). | 


//7PRIMER JOB WTSC,IBM,MSGLEVEL=1 
//PRIMODU2 EXEC PGM=IEHDASDR 
//STEPCAT DD DSNAME=PRIMER .UCAT1 ,»DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//DISK1 DD UNIT=3330,DISP=OLD,VOL=SER=WTVSAM 
/7TAPEL DD VOL=( ,RETAIN; » »SER=057454) ,UNIT=3400-6, 
(7? LABEL=(1,SL), | 
J? DSN=DUMPVS1 , DISP=(NEW, PASS) 
//SYSIN DD * 
DUMP FROMDD=DISK1, TODD=TAPE1 
7*® 


The output is as follows: 


IEH806I DUMP TO DDNAME=TAPE1 IS COMPLETED 
IEH839I HIGHEST RETURN CODE ENCOUNTERED WAS 00 


Note: 


The //STEPCAT DD statement is necessary when a VSAM object resides 
on the volume (Cotherwise a 913 ABEND is issued). 


The operator was prompted to enter the VSAM catalog master password 
(the catalog was defined with passwords (see page 102). 


The second Job restores the volume. 


It is assumed that there is a valid VSAM catalog with the name 
PRIMER.UCAT1 on the volume. For the JCL specification see the 
appropriate Utilities manual. 


//PRIMER JOB WTSC,IBM,MSGLEVEL=1 
/7PRIMORE2 EXEC PGM=IEHDASDR 
//STEPCAT DD DSNAME=PRIMER .UCAT1,DISP=OLD 
//7SYSPRINT DD SYSOUT=A 
//TAPEL DD VOL=(,RETAIN;> > »SER=057454 ) ,UNIT=3400-6, 
// LABEL=(1,SL), 
7 DSN=DUMPVS1 ,DISP=OLD 
//SYSIN DD * 
RESTORE TODD=STEPCAT ,FROMDD=TAPE1,PURGE=YES 
/¥® 


The output is as follows: 


IEH806I RESTORE TO DDNAME=STEPCAT IS COMPLETE. VOLUME SERIAL NO.=WTVSAM 
IEH839I HIGHEST RETURN CODE ENCOUNTERED WAS 00 
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A.6 CATALOG DEVICE CONVERSION 


The only utility currently available to do direct device conver- 
sions of VSAM catalogs is REPRO "COPYCAT’' (see section B.3 on page 
272). This however is an MVS exclusive and only works for nonre- 
coverable catalogs. The following also discusses other alterna- 
tives with RCATs and other SCPs. 


If a catalog needs to be reorganized, or its allocation needs to be 
changed, a catalog copy function needs to be performed. The 
considerations involved are generally the same as device conversion 
and are mentioned below. 


A.6.1 NONRECOVERABLE CATALOG DEVICE CONVERSION (MVS) 


REPRO ‘'COPYCAT' (section B.3 on page 272) can be directly used to 
move a catalog from one device to another. A new empty catalog can 
be defined on the new volume and the old catalog copied into it. 
The new catalog must have a different name, be ona different 
volume and be large enough to contain all the extents of the old 
catalog. Additionally both catalogs must be nonrecoverable. 


Following the "COPYCAT’ function the user must EXPORT DISCONNECT 
the original catalog and delete the cluster entries that described 
the original catalog and which now resides in the new catalog. This 
Function will make the old catalog space available, clean up the 
volume's FH DSCB and write a new Volume Record for the old volume 
in the new catalog. The new catalog now owns the old volume. 


If the Master Catalog (MCAT) device is being converted or copied, 
the SYSCTLG member of the SYS1.NUCLEUS must be changed to point to 
the new MCAT device, followed by an IPL (see description on page 
81). Subsequent to the IPL the DELETE and EXPORT DISCONNECT action 
must be taken. 


When "'COPYCAT’' is being used for device conversion, the user must 
define a new catalog with a different name than the original and it 
must also reside on a different volser number. The reasons for this 
are because the DEFINE process of the new catalog involves writing 
an entry in the MCAT which points to the new catalog. This entry 
cannot obviously have the same name as the original source catalog. 
Since the source and target volumes must also be mounted when whe 
actual copying is being done, the. target volume must also have » 
different volser. If the user wants to retain the same volser 
and/or retain the same catalog name, there is no easy straightfor- 
ward utility command available to accomplish the task. 
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What has to be done is the execution of two sets of 'COPYCAT'. 
The. first step would be a 'COPYCAT' to an interim catalog on any 
scratch volume. The entire 'COPYCAT' process including EXPORT 
DISCONNECT and DELETE CLUSTER of the original sources must be 
executed here. The second step would be the definition of the new 
catalog with the same catalog name on the new volume of the desired 
devicetype and bearing the same volser name, followed by the 
"COPYCAT' function from the interim catalog on the scratch volume 
to the new devicetype. 


An additional consideration is the question of the UCAT associated 
ALIAS names. These ALIAS names do not reside in the UCAT itself. 
They are associated with the user catalog record (U record) in the 
MCAT that points to the UCAT volume. 


When the catalog copy is done and the EXPORT DISCONNECT command is 
issued against the original source catalog (and this must be done), 
it deletes the U record and associated ALIAS entries from the MCAT. 
The new version of the UCAT is left without its ALIAS names. AS a 
consequence of this it is generally a good idea to do a LISTCAT of 
the original source catalog's U entry in the MCAT, before 'COPYCAT! 
is done. The output of this run can be directed to SYSPRINT so a 
hardcopy of the ALIAS names is produced or it can be directed to 
some tape or disk data set for subsequent retrieval. 


Subsequent to the 'COPYCAT' procedure, the user, using the LISTCAT 
output, can either manually, (via the Access Method Services DEFINE 
ALIAS command), or via a user-written program, (that retrieves the 
ALIAS names from the output data set of LISTCAT and generates 
DEFINE ALIAS commands) rebuild the ALIAS names for the new UCAT. 


A.6.2 NONRECOVERABLE CATALOG DEVICE CONVERSION 


REPRO 'COPYCAT' not being available with DOS/VS, SVS, and VS1, the 
only choice the user has for device conversion is via EXPORT/IMPORT 
of individual data sets. The REPRO Unload/Reload function available 
here will not help since it has a requirement that the reload must 
be done to a catalog with the same name and devicetype. 


Each data set in the catalog being converted must be backed up. 
This can be done either via REPRO or EXPORT. Once everything is out 
of the catalog being converted, it can be deleted and removed. A 
DEFINE for the new catalog must be issued, on the new device type, 
and the data set entries moved back into it. I£f REPRO was used for 
backup, the data set can be manually redefined in the new catalog 
followed by the REPRO of the data. If EXPORT was used the data set 
can now be imported. IMPORT, generally speaking, is nothing more 
than a DEFINE followed by a REPRO issued by Access Method Services. 
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With Enhanced VSAM (DOS/VS Rel. 31, VS1 Rel.4 and up, SVS Rel. 1.7 
with ICR, and MVS Rel. 3.0 with ICR and up) a data set can be 
predefined and then IMPORTed into. If the data set, as it is 
defined in the catalog is empty (IMPORT checks this) the existing 
definition in the catalog will be used. If the data set is indicat- 
ed as nonempty in the catalog and is being IMPORTed into, IMPORT 
Will issue a delete, followed by a DEFINE based on information on 
the portable tape data set produced by EXPORT, and then REPRO the 
data set in. 


During the IMPORT process, since sequential VSAM I/0 is being done, 
any KSDS being imported will be reorganized. The important point to 
remember here is that some of the important performance options 
(such as FREESPACE) originally specified for the data set should 
probably be changed. If for example FREESPACE (50 50) was original- 
ly specified for the data set in anticipation of insert activity 
subsequent to the original load process, since these records 
probably now do exist in the data set, the FREESPACE parameter 
should be reduced. Since the REPRO or IMPORT functions are essen- 
tially reload functions, users should make a point of rechecKing 
the parameters that are specifiable at DEFINE time and make the 
appropriate changes (with IMPORT the FREESPACE value can only be 
changed if the data set is imported into an empty cluster). 


Note: Since device types have different cylinder capacities the 
Space parameters must be checked £for accuracy on the new device 
type. 


Since the data sets involved are being totally reloaded into the 
new catalog the catalog statistics information is also changed. It 
is as if we have anew data set with no accumulated statistical 
information available. 


Since EXPORT/IMPORT does not support nonVSAM data sets, any nonVSAM 
data sets cataloged in the old catalog must be manually recata- 
loged. 7 


A.6.3 RECOVERABLE CATALOG DEVICE CONVERSION 


Prior to the availability of the Access Method Services RESETCAT 
command, the only tool available to do this Kind of conversion were 
either EXPORT/IMPORT Or EXPORTRA/IMPORTRA. The consideration 
relative to these commands are the same as was discussed in the 
previous section. EXPORTRA/IMPORTRA essentially do the same _ as 
EXPORT/IMPORT but they do it through the catalog entries in the 
CRAS on each owned volume. 
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The 
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major differences are as follows: 


With EXPORTRA one can point to a certain CRA and issue 2 
EXPORTRA ALL command rather than individually EXPORT or EXPOF- 
TRA each entry. This involves, of course, less work by the 


user. 


EXPORTRA also Supports nonVSAM names cataloged in CRAs and will 
also move these to the portability tape Cor disk). Unlike 
EXPORT/IMPORT, the user does not have to manually reenter the 
nonVSAM entries; IMPORTRA can be used instead. 


IMPORTRA always does a delete followed by a redefine. With 
IMPORT if the existing catalog entry for the data set being 
imported indicated that it was empty, the existing definition 
would be used. This is not the case with IMPORTRA. 


If an EXPORTRA ALL was originally coded, there is no tool 
available to do individual IMPORTRA entries (DSN). It is an all 
Or nothing proposition. 


Both EXPORTRA and IMPORTRA only support recoverable catalogs 
Which are only available in Enhanced VSAM. Until Enhanced VSAM 
Support became available in SVS (with ICR), none of what is 
discussed here was available to SVS users. 


The Access Method Services command RESETCAT became available in 


 DOS/VS Rel. 33, in VS1 Rel.6, in SVS with the VSAM ICR, and in 


MVS via SU 8’. Its primary function is to rebuild a catalog 
through the duplicated entries in the owned volume CRAs. Using 
this information a catalog is rebuilt. 


Although not designed to be used as a conversion tool, it can 
be used to do so. If the RESETCAT function is directed to a new 
catalog, the entries in this catalog are rebuilt via the CRA 
contents. RESETCAT cannot be used against an MVS live master 
catalog. It requires the exclusive control of the catalog being 
reset which is not possible in the case of the MVS MCAT. 


The steps involved in using RESETCAT to do device conversion 
for a recoverable user catalog are listed below. The new 
catalog can be ona different devicetype, different volume 
serial number and can also have different space allocation 
values. The only restriction is that it must have the same 
name as the catalog that originally produced the CRAs involved. 
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anew RCAT involves the steps listed below. As an 
example let us assume that a UCAT called CAT1 which is on volume 
OLDVOL is being moved to volume NEWVOL. CAT1 owns volume VOL1 and 
VOL2 in addition to OLDVOL. 


Resetting into 


Action 


Using IEHDASDR (CFASTCOPY 
for DOS/VS) backup all 
volumes involved. 


LISTCAT ENTRIES (CAT1) ALL 
CAT (master catalog name) 
(OS/VS only). 


EXPORT DISCONNECT CAT!1. 


DEFINE new catalog called 
CAT1 which 1s recoverable 
on volume NEWVOL. 


RESETCAT into CAT1 on 
NEWVOL pointing to the 
CRAs on VOL?1, VOL2 and 
OLDVOL. 


Explanation 


T£ an error condition occurs 
uring RESETCAT, then the 
rolumes can be restored. 


List the user catalog entry in 
the MCAT to get a list of ail 
its ALIAS names. 


Deletes the MCAT entry £for 
CAT1. Also deletes ALIAS names 
for CAT!. 


Rebuild CAT1 based on the in- 
formation in CRAsS on all owned 
volumes, we now have a new 
RCAT on NEWVOL. 


At the completion of this process, the user should proceed to 
thoroughly check the new-catalog. The space which the old catalog 
occupied on OLDVOL is now available for suballocation and is owned 
by the new catalog. 


A.7 CATALOG REORGANIZATION 


The High-Keyrange portion of a catalog could require periodic 
reorganization. It currently consists of 10% (DOS/VS Rel.34 20%) of 
the total allocated space of a catalog and it is subject to CI and 
CA splits. The reorganization of the catalog essentially involves 
the rewriting of all its. contents. This can be done if a new 
catalog is defined anda recent backup copy of the catalog is 
restored into it. 


In MVS the REPRO 'COPYCAT' function can be used to copy a nonrecov- 
erable catalog into another catalog (see section B.3 on page 272). 
The disadvantages of "COPYCAT', as described earlier, is that the 
new catalog will have a new name unless 'COPYCAT' is executed twice 
with the first execution producing an interim version of the 
catalog. 


REPRO Unload/Reload, if the reload is done to a new catalog, can be 
used to reorganize the catalog. It requires that the catalog being 


reloaded have the same name and device type and volser as’ the 
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originally unloaded catalog. It also works with RCATs as opposed to 
'COPYCAT' that does not. It can also be used to rebuild a catalog 
if it has run out of extents or if the user wants to consolidate 
all of ‘the extents into one extent (for UNLOAD/RELOAD considera- 
tions see also section A.5.1 on page 254). 


It is always necessary to insure that the particular catalog 
involved in an Unload/Reload operation is quiesced. If this is not 
done, since a backup/restore operation is involved, out of sync 
conditions could arise that could make either the catalog or some 
data sets unusable. 


A.7.1 REORGANIZING A NONRECOVERABLE CATALOG 


The steps are as follows: 


Action Explanation 
1. LISTCAT ALL the UCAT To have a list of catalog 
entries. 
2. LISTCAT ENTRIES (CUCATname) To get the catalog ALIAS 


ALL CAT(master catalog name) names. 
COS/VS only). 


3. EXPORT all of the VSAM data 
sets that are wholly or 
partially contained on the 
catalog volume. 


Y, Unload the catalog to tape 
or disk uSing REPRO. 


5. EXPORT DISCONNECT the To remove its name and ALIAS 
catalog. names from MCAT. 

6. ALTER REMOVEVOLUMES on the Function is not available in 
catalog volume to clean up old VSAM. Volume clean up 
the volume. can be done via super- 


Zapping OFF the VSAM 
ownership-bit in the FY DSCB 
followed by IEHPROGM SCRATCH. 
7. DEFINE new catalog on the | 
same volume, with same name. 
Allocation amounts could be 
larger. | 


8. Reload the catalog (REPRO). 


9. IMPORT all data sets EXPORTed 
in step 2 above. 


10. Manually restore the ALIAS 
| names for the UCAT COS/VS only). 
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A.7 2 


Reorganizing a recoverable catalog 


1Q. 


11. 


Action 


LISTCAT ALL user catalog. 


LISTCAT ENTRIES CUCATname) 


ALL CAT(master catalog name) 


(OS/VS only). 
EXPORTRA ALL out of CRA on 
catalog volume. 


EXPORTRA ENT (multivolume 
data set) of data sets that 
wholly or partially reside 
on catalog volume. | 
Unload the catalog to tape. 


EXPORT DISCONNECT catalog 
from master catalog. 

ALTER REMOVEVOLUMES catalog 
volume. : 

DEFINE new RCAT on same 
volume. 

Reload into new catalog. 


IMPORTRA all data sets ex- 
ported in steps 2 and 3 
above. 

Rebuild the ALIAS names for 
UCAT. 


REORGANIZING A RECOVERABLE CATALOG 


involves some additional steps, 
since Unload/Reload opens a catalog as a 
of CRAs. 


data set and is not aware 
Explanation 


To have a list of catalog 
entries. 

To get a list of the UCATs 
ALIAS names out of the master 
catalog. 

To capture all of VSAM and 
nonVSAM data sets on the 
catalog volume. 

Get the multi volume data 

set names from step 1 above. 


Use Access Method Services 
REPRO. 


Cleans up pack and deletes 
all VSAM information. 
Could have larger extents. 


Use Access Method Services 
REPRO. 

Restores all VSAM and nonVSAM 
data sets. 


A.8 CHANGING THE ALLOCATION OF A NONRECOVERABLE CATALOG. 


It ais always 
extending into secondary 


a good idea to 


give 
extents if it needs to do so. 


the capability of 
A surpris— 


a catalog 


ingly large number of VSAM catalog users have not done so. 


Once a decision is 
with secondary 
problem of what to 
associated with the catalog. 
the UCAT 
tered in the MCAT, 
as ina TSO environment) 
could always 
generate DEFINE 


allocation amounts 


Write a 
ALIAS commands 


made to reorganize a catalog or 
specified, 
do with possibly a large number 
These ALIAS names will be deleted when 
1s EXPORT DISCONNECTed and 
but if quite a few of 
the process could take a long time. 
utility: that would 
COS/VS only). 


to redefine it 
user faces the 
of ALIAS names 


the 


can always be manually reen- 
these are involved (such 
A user 
output and 
Failing this, the 


take LISTCAT 


process mentioned below can be used for nonrecoverable UCATs. 
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Since the process described below involves backup and restore of. 
the MCAT and the UCAT, the access to these objects should be 
absolutely minimized. Any changes made to .these after they have 
been unloaded will not be reflected in the catalogs after they have 
been restored. Of particular. interest, in the case of the MCAT, are 
MVS PAGE data set and SYS1.STGINDEX. Activity against these data 
sets should be minimal Chence a quiesced standalone environment) to 
prevent their extension between the MCAT unload and subsequent 
reload. | 3 | : 


Action | Explanation 


1. Quiesce the system. The following steps involve 
MCAT backup/restore. It is 
necessary to have a stand- 
alone quiesced system to 
do the following. 


2. Backup MCAT and UCAT | For recovery purposes if an 
volumes. | error condition occurs. 
3. Unload MCAT to tape. | This step copies all of the 


UCAT's ALIAS names to tape. 
4u. EXPORT all VSAM multi oz 
Single volume data sets on 
UCAT volume. 


5. Unload UCAT to tape. 


6. EXPORT DISCONNECT UCAT. Deletes UCAT entry and its 
. ALIAS names from MCAT. 
7. ALTER REMOVEVOLUMES UCAT Cleans up UCAT volume. 
volume. 
8. DEFINE new UCAT. Should have secondary alloca- 


tion specified and be larger 
than all extents of original. 


9. Reload into UCAT. Restores UCAT to original 
: contents and reorganizes HEk. 


10. IMPORT data sets EXPORTed 
in Step 5. 


11. Reload MCAT. Reloads MCAT and restores 


UCAT's original record and 
its associated ALIAS names. 
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A.9 ¢€ GING TH A EF VSAM ALO 

The ALTER NEWNAME command of Access Method Services does not 
support VSAM catalog name changes. If a catalog name is specified 
on this command, catalog management checks the old name against the 
catalog name and if they match, the command will be rejected. The 
primary reason for this rejection is for integrity purposes. 
Catalog management cannot allow a catalog name change if there isa 
possibility that it might be shared with another region, address 
space or CPU. 


Currently the only means available to change the catalog name, is 
via its deletion and redefinition. The user must of course capture 
all the entries in the catalog, via EXPORT, EXPORTRA or REPRO, 
essentially emptying it out, prior to deleting and redefining it. 
This is a very time consuming task. Additionally if the catalog is 
nonrecoverable, EXPORT does not support nonVSAM entries either, so 
subsequently these entries must be manually recataloged. (EXPORTRA 
for recoverable catalogs does support nonVSAM entries.) 


In MVS, with nonrecoverable catalogs, "'COPYCAT' can be used simply 
to copy the catalog into a new one with the new desired name. 
"COPYCAT' however is not available in DOS/VS, SVS, VS1 nor does it 
support recoverable catalogs. | | 
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B:0 APPENDIX B. OS/VS CATALOG CONSIDERATIONS 


B.1 USING OS/VS SERVICE AIDS AND UTILITIES WITH VSAM 

B.1.1 PRINTING A VSAM CATALOG WITH OS/VS UTILITIES 

B.1,1.1 PRINT PARTS OF A CATALOG WITH ITEHDASDR/DRWDASDR 

The IEHDASDR/DRWDASDR utility can be used to print all catalog 

extents including index and sequence sets. 

If the volume is owned by auser catalog, a STEPCAT or JOBCAT 

DD-statement must be provided. | 

. The output of LISTCAT (starting on page 142, contains the 
catalog extents as follows (see also description on page 148). 


section: CLUSTER ------- -PRIMER.UCAT1 
group: DATA” aounecs VSAM. CATALOG. BASE .DATA. RECORD 


-. The first ‘VOLUME’ group (describing the "Low-Keyrange' ) 
contains the beginning of the catalog: 


EXTENTS LOW-CCHH----X'00010000' 
= The second 'VOLUME' group (describing the 'High-Keyrange') 
contains the end of the catalog (1£ no extents exist): 


EXTENTS HIGH-CCHH---X’'00020010' 


° To print the catalog use the following job: 


//LIST EXEC PGM=IEHDASDR 

//STEPCAT DD DSN=PRIMER.UCAT1 ,»DISP=SHR 

//SY SPRINT DD SYSOUT=A 

7/001 DD UNIT=3330, VOL=SER=WTVSAM,DISP=SHR 

//SYSIN | DD x | 

DUMP FROMDD=DD1, | x 

TODD=SYSPRINT> - * 
BEGIN=00010000, | x 


END=00020010 
/*® 
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The AMASPZAP (MVS, SVS), or HMASPZAP (VS1) program can be used to 
print catalog extents, including index and sequence sets. 


A STEPCAT or JOBCAT DD-statement must be provided. 
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Obtain the begin and end of the catalog as described in section 
B.1.1.1 on page 267). 


LOW~CCHH----X'00020000' 
HIGH-CCHH---X'00020020' 


Execute utility IEHLIST with the LISTVTOC function (see page 
245). 7 


The printout shows the catalog data space name as follows: 


Z9999994.VSAMDSPC . TXXXXXXX. TYVYYYYY 


To print the catalog the following job may be used: 


//LIST EXEC PGM=AMASPZAP 
//STEPCAT = DD DSN=PRIMER.UCAT1,DISP=SHR 
//SYSPRINT 0D SYSOUT=A = : / 
//SYSLIB DD DSN=Z99999994. VSAMDSPC . TXXXXXXX.TYYYYYYY > \ 
11 UNIT=3330, VOL=SER=WTVSAM ,DISP=OLD 
//SYSIN DD % 
ABSDUMPT 00010000 00010010 ~~ WILL PRINT SPECIFIC EXTENTS 
ABSDUMPT ALL WILL PRINT THE ENTIRE CATALOG DATA SPACE 
/*® 
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B.1.2 HOW TO CHANGE OWNERSHIP BITS AND VOLUME TIMESTAMP: 


For all functions described in the next three sections DOS/VS users 
may use the TKQVDU utility (described on page 179). 


The functions described in the next three sections are a violation 


of VSAM data set security and protection and should only be used in 
critical situations. | 


A description of the ‘data set security bit’ is included in section 
2.10.2 on page 45. 


A description of the ‘VSAM ownership bit' is included in section 
2.10.1 on page 44. 


A description of the 'VSAM volume timestamp’ is included in section 
A.2 on page 244. | 


B.1.2.1 2URN OFF THE "DATA SET SECURITY BIT’ (OS/VS) 


When the catalog cannot be opened due to I/70 errors or damaged 
self-defining records, the only way to print the catalog without 
STEPCAT is turning off the ‘data set security bit’ (Cin OS/VS 
systems also called 'OS/VS password protection bit') in the Format 
1 DSCB (see page 245 note 10 ) for the catalog data space. 


The following procedure can be used to turn off the ‘data set 
security bit' 


e First execute utility IEHLIST with the LISTVTOC function to get 
the 'cecchhhhrr' of the FORMAT-1 DSCB of the catalog space with 
the name "Z9999994.VSAMDSPC.TxXXXXHKKX.Tyyyyyyy' (see section 
A.2.2 on page 245). 7 

e Then turn the ‘data set security bit’ OFF with the following 


Job: 
//ZAP EXEC PGM=AMASPZAP 
//7SYSPRINT DD SYSOUT=A 
//7SYSLIB DD DSN=FORMAT4.DSCB,UNIT=3330, 
V1 VOL=SER=WTVSAM,DISP=OLD ,DCB=KEYLEN=44¢ 
//SYSIN DD % 
CCHHR CCCCHHHHRR 7*XOBTAIN FROM FORMAT-1 DSCB*/ 
VER 005D 10C0 
REP 005D 00co /*TURN OFF ‘DATA SET SECURITY BIT’ */ 
/® 


Note: 


The SYSLIB to be specified is always 'FORMAT4Y.DSCB' even though the > 
Format-1 DSCB is modified. 
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B.1.2.2 


If a disk contains VSAM objects which should be deleted and the 
VSAM catalog which owned the volume is not accessible or not 
available any more, one way to use the volume for VSAM objects is 
to turn the VSAM ownership bit off. , 


In DOS/VS the IKQVDU Gees (described on page 179) can be used. 
In OS/VS the following method or ALTER REMOVEVOLUMES (see example 
on page 181) can De used. 


The ‘VSAM ownership bit’ in the Format-4% DSCB is shown on page 245 
note 4. 


/7ZAP EXEC PGM=AMASPZAP 
/7SY SPRINT pD SYSOUT=A 
//SYSLIB DD DSN=FORMAT4 .DSCB,UNIT=3330> 
Vl VOL=SER=WTVSAM,DISP=OLD ,DCB=KEYLEN=44 
/7SXSIN pp % | 
CCHHR CCCCHHHHRR /*OBTAIN FROM FORMAT-4 DSCB*/ 
VER 0054 80 
REP 0054 00 /*TURN OFF VSAM OWNERSHIP BIT */ 
7% 


B.1.2.3 MODIFY THE VSAM VOLUME TIMESTAMP COS/VS) 


As described in section A.5.1 on page 254 a catalog may be out of 
sync with its volume(s) after either reloading a backlevel catalog 
or a backlevel volume containing the catalog. 


To enable access to the VSAM data sets for recovery purposes the F4 
"volume timestamp’ (see page 245) must be changed to exactly the 
same value as the 'volume timestamp’ in the catalog's volume record 
(see page 159). ; : 

The catalog timestamp is shown on page 159. 


The VTOC volume timestamp is shown on page 245 note 6. 


The Format-4 ‘volume timestamp' may be modified with the following 
job: a | | 


F7ZAP EXEC PGM=AMASPZAP 

/7SYSPRINT DD SYSOUT=A 

//SYSLIB DD DSN=FORMAT4.DSCB,UNIT=3330; 

Gf VOL=SER=WTVSAM ,DISP=OLD , DCB=KEYLEN=44 

//SYSIN DD * 
CCHHR CCCCHHHHRR /* OBTAIN FROM LISTVTOC */ 
VER | 0057 XXXXXXXXVYVVVYVYVYVY 7* OBTAIN FROM LISTVTOC */ 
REP 0057 XXXXXXXAXVVVVVVYVY 7* OBTAIN FROM LISTCAT */ | 

/* 
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B.2 CATALOG PERFORMANCE CONSIDERATIONS (COS/VS) 


As described in detail in the following sections, VSAM catalog 
management uses multi-string direct I/70 to read the catalog. 


The default buffer space (3K) allows to build 2 strings. 


If a catalog is used by many users/programs additional strings may 
improve performance dramatically. 


The following table shows the relation of buffer space, defined 
with the BUFSP parameter at DEFINE time and the number of resulting 
strings. 


BUFSP Strings _Index Buffer Data Buffer 
3 K 2 3 3 
4uK 3 uy 4 
5 K 4 5 5 
6 K 5 6 6 
7 K 6 7 7 
8&8 K 7 8 8 
9 K 7 10 8 
10 K 7 12 8 


Theoretically there is no limit in specifying a large amount of 
BUFSP. This is not yet documented in Access Method Services 
Manuals. The specified buffer space in excess of 8K is added to 
number of index buffers. | 


When using shared UCB to access a catalog from multiple CPUs “71 
buffers are refreshed for each access. This may decrease perfor- 
mance when usSing too many buffers. 
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B.3 COPY CATALOG - CATALOG (REPRO) (MVS ONLY) 


The following terms are used: 


COPYCAT = is a terminology used loosely to. describe the REPRO 


function which copies a VSAM earareg into another 
VSAM catalog (MVS only) 7 
CRA = Catalog Recovery Area 
MCAT = VSAM Master Catalog : | 
RCAT = VSAM Recoverable Catalog (user or master Cee 
UCAT = VSAM User Catalog 7 
"COPYCAT' is an MVS exclusive function. It allows an MVS user to 
copy aecatalog directly into another new catalog. The target 
catalog must be a new empty catalog, but it could have a different 
name, volser and devicetype than the source catalog. Thus it is a 


very nice tool to he used by MVS users for catalog device conver- 
Sion or backup. | - | 


"COPYCAT' only supports regular (nonrecoverable) catalogs. Ts 
either the source or the target is recoverable, "COPYCAT'’' stops. 
The reason for this is that 'COPYCAT’ opens both catalogs as VSAM 
data sets and uses regular VSAM GET/PUT logic. Thus it bypasses any 
kind of CRA processing which of course, if 'COPYCAT' with recovera- 
ble catalogs were allowed, would cause catalog-CRA out of syne 
conditions. Hence no support for recoverable catalogs (here called 
"RCAT') at all. 


In the process of copying, 'COPYCAT' copies the self describing 
records of the original source catalog also (it is simply doing CI 
by CI reads and writes.) It is up to the user to delete these 
entries subsequent to the copy function. The user must also realize 
that until such a point as the original source Catalog is deleted, 
we have 2 catalogs owning the volumes and data sets involved. This 
is a severe integrity exposure that should be immediately remedied 

he user deleting the source cataloqg's ‘cluster entry in the new 
target catalog. This DELETE run cleans up the F4Y DSCB VTOC on the 
Original catalog indicating that the catalog is gone and frees up 
the original catalog space. It also deletes the source catalog 
self-describing records and cluster entries in target. The MVS 
Access Method Services SRL (see page 2) describes this function 
further under the topic of "Copy - Catalog Procedure” in the 
chapter "Copying and Printing". | 


B.4 OS/VS CVOL CATALOG VERSUS VSAM CATALOG 


The discussion is designed to give the reader enough pertinent 
information such that an appropriate decision can be made in 
deciding between VSAM User Catalogs (UCATs) and OS/VS. CVOLs. It 
Will however point out important considerations that can be used by 
any SCP user to determine the contents of each type of catalog. 
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The following terms are used: 


CVOL = OS/VS System Catalog 

HKR = High-Keyrange 

LKR = Low-Keyrange 

MCAT = VSAM Master Catalog 

RCAT = VSAM Recoverable Catalog (user or master catalog) 
UCAT = VSAM User Catalog 


This discussion does not reference any direct performance figures. 
Benchmark figures in this type of comparison would be meaningless 
Since performance, as it will be pointed out, is dependent on the 
contents of each catalog and the type of processing done. Any UCAT 
oriented discussion naturally applies to the MVS MCAT also since 
the MCAT is nothing other than a UCAT that is designated by the 
user as an MCAT. 


B.4.1 VSAM USER CATALOG ADVANTAGES (OS/VS) 


The following section discusses the more favorable aspects of a 
VSAM catalog. | 


e A VSAM catalog's index structure is a balanced tree. Additions 
or deletions to the catalog do not change the structure, i.e. 
gaps are not introduced and fragmentation does not occur. So 
the performance of the catalog does not necessarily degrade 
With additions or deletions (in some cases the DEFINE perfor- 
Nance may decrease significantly if many VSAM data sets are 
defined on the same volume). 


° A VSAM catalog supports both VSAM and nonVSAM entries. | 


° VSAM catalogs can be shared between virtual SCP systems with 
total integrity. 


° VSAM catalogs are also totally portable between systems. A MCAT 
can be taken over to another system and used as an MCAT or 
connected as a UCAT to the existing MCAT. The incompatibilities 
in terms of portability or sharing possibilities are only 
relative to Recoverable Catalogs (RCAT) in cases where an SCP 
does not support RCATs (SVS until April 77). | 


° VSAM catalogs certainly do not suffer from lack of utility 
Support. In fact if there is a problem it is the other way 
around where there are many utilities that a user has to know 
about and learn. | | 7 | 


° If we use VSAM catalogs we have the capability of using Recov- 
erable Catalogs (RCAT) which is certainly a useful feature to 
have. They, unlike. other catalogs, give you the capability of 
having a dynamic backup structure such that at any given point 
in time your backup is totally up to date and in syne with your. 
catalog. We additionally have a comprehensive set of utilities 
to access this backup structure for recovery purposes. All of 
this is available without any major loss in performance. 
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m1 


B.4. 


JOBCAT/STEPCAT DD cards give a user the sa aut of Tiveerine 


a request to a particular catalog. This reduces the. search| pace 
length and is optimum in terms of Salad 


Qne can specify additional new fields Fox gue nonvean>aate 


sets ina VSAM catalog. Owner ID and retention period are new 


fields in addition to the normal volser, devicetype informa- 
tion. 


In terms of protection VSAM catalogs have the added function of 
password protection. Three levels of passwords, Master, Update 
and Read levels can be specified ‘for a catalog. The ‘fourth 
type, CI level password, does not really have any meaning with 
VSAM catalogs (see also description of passwords on page 52). 


2 NSAM HSER CATALOG DISADVANTAGES (Os/v5) 


The following is a compilation of une avexenie eens relative to 
VSAM catalogs. | 
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A lot of users, specially MVS MCAT users would like a relaxa- 
tion of volume ownership rules. These rules limit the ownership 
of a volume to only one VSAM catalog. This rule only applies to 
VSAM data sets. NonVSAM data sets on an owned VSAM pack can of 
course be cataloged in. any OLhee catalog. 


VSAM Saeetegs geneeatis end up being very large objects. 
Especially compared with oOS/VS CVOLs they are much larger. 
There is a good deal of space in the Low-Keyrange of VSAM 
catalogs specially for nonVSAM entries. But then again for VSAM 
entries there is a great deal more information recorded than 
what we have been used to.. ~~? _ 2 ©s | | 


The big size of a catalog, apart from obvious disk space 
considerations, makes the DASD arm seek Span larger which is a 
performance consideration. : | | 


The number of I/70s required to locate anything ina VSAM 
catalog is more than likely a minimum of 3. As an example to 
locate a nonvSAM single volume entry, catalog management must 
read the following: 
1. High level index record 

No I70. This is Kept in storage after the very first access. 


2. An intermediate level index record if the number of index 
levels are Pence Woen 2 | 7 , ) 


3. A sequence set record. This however can be in storage in an 
index buffer 3 | | a 


4, the, High tee ange record 


VSAM PRIMER and REFERENCE | 


Be 


5. The Low-Keyrange record. 


Catalog management uses VSAM multi-string direct I/70 to zead 
the catalog. This type of I/O invalidates the data buffer after 


the buffer is released, i.e. when the I/70 is done, so the 
likelihood of finding any valid data associated with the string 
being used is very low. So at least the HKR and LKR records 


must be read. The sequence set record will probably have to be 
read since multiple strings do not share sequence set buffers 
hence the likelihood of a string finding a sequence set record 
associated with its buffer is minimal. 


VSAM KSDS's currently suffer from a phenomenon,explained below, 
Which in general is referred to as the "Space Reclamation 
problem." A VSAM catalog being a KSDS suffers from this 
problem. h roblem i Owe vi imited only to the Hk 


For every data CI ina KSDS, there is an entry ina sequence 
set record. This entry contains the compressed key of the 
record with the highest key in the CI. Keys, when they arrive 
into the index component, are compressed relative to what key 
had arrived prior to them and what will come after them. They 
are front and rear compressed. One can have a 255 byte key that 
gets compressed down to 1 byte by the time it gets into the 
sequence set record. Because of the compression they actually 
express a range of possible keys as opposed to an actual key 
associated with the particular CI. | — 


With the current implementation, all the records in a CI can be 
erased so that it is totally empty, however the sequence set 
pointer is not removed. As long as the sequence’ set pointer 
remains where it is, the only way one can put a_ record into 
this empty CI, is via coming in with a record whose key £fits 
Within the range described by the sequence set pointer. If this 
is never the case, the CI will always sit there, taking space 
and never being used. The space will never be reclaimed. Hence 
the "Space Reclamation Problem.” 


In normal KSDS type of processing, it being considered a 
randomly retrieved or accessed kind of object, there is no 
problem of space reclamation. Random access means just that. 
The likelihood of coming in with a key that fits in the range 
described with the sequence set record is very good. In certain 
cases however, we might have this problem. If we are always 
inserting records that have successively higher Key values and 
never coming in with lower keys we will have this problem. 


VSAM catalogs suffer from this problem when GDGs are cataloged 
in them and the GDG generation numbers are never reused. Each 
generation of a GDG has a key higher than the previous key. If 
we delete a GDG base and never reuse those same generation 
numbers Cunlikely Situation') we will have the nee os space in 
the HKR and. only the HER. 


The problem used to be ‘ae the old version of VSAM. 
Generated VSAM names aseare consisted of 8 bytes of the time of 
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day clock value. So they were always in ascending sequence. 
Their subsequent deletions did not do any good because other 
generated keys always had a higher value. Enhanced VSAM fixed 
this particular problem by taking the TOD value and breaking it 
in half, putting one half in the front of the name and the 
other half on the other end, thus making the name totally 
random. — | | | | 


If a user currently uses GDGs_ the way it is explained above, 


his/her choices are twofold: 


(1) Do not put GDGs in VSAM catalogs; 

(2) Periodically reorganize the catalog via the Repro Access 
Method Services command. More on this later (see section A.7 on 
page 261). | | oo 


There is no GDG support in VS1/SVS VSAM catalogs. If a GDG Base 
or new generation is cataloged in a VSAM catalog during an MVS 
migration process and the catalog is subsequently moved back to 
VS1/SVS, the new GDG entries must be manually recataloged in an 
appropriate CVOL. Additionally there is no ALIAS name support 
in SVS/VS1 VSAM catalogs. 


ALIAS support is an MVS exclusive support which is mainly used 
for CVOL or UCAT entries. Data set names cataloged in MVS CVOLs 
or UCATS are mostly accessed through qualified data set names 
that have the ALIAS of the CVOL (Cor UCAT) or the catalog name 
as a ‘first level qualifier. This support is not needed in 


SVS/VS1 because ALIAS: support for CVOLs has always been avail- 


able in these systems and of course STEPCAT/JOBCAT DD cards are 
the only means of accessing VSAM catalogs even if the entries 
are qualified. | : | 


VSAM catalogs require a good deal of virtual storage for 


buffers and control blocks. In an SVS environment all of the 
catalog control blocks are fixed for the duration of the OPEN. 


In VS1 and MVS (Enhanced VSAM) these control blocks and buffers 
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are ‘not fixed; they are pageable. These required control blocks 
and buffers get fixed only for the duration of the I/0. 


Generally speaking, for a KSDS, the amount of storage needed 
for control blocks is equal to 4560 + 1560 (S - 1) where S it 
the number of strings. A VSAM catalog being a KSDS, therefore 
requires a minimum of 4560 + 2560, i.e. 7120 bytes of control 
blocks. This is for the case when bufferspace of 3K is speci- 
fied which translates into 2 strings. The 3K of buffers is on 
top of this which makes it approximately 10K of virtual 
storage. Of this amount only 224 x S (MVS) or 72 x S (VS1) is 
always fixed. The rest is pageable common storage. 


To summarize, a VSAM catalog requires anywhere from 10K (2 
strings) to 20K (7 strings) of virtual storage. This storage 
comes out of protected common storage areas. CSA in MVS and SQA 
in VS1. Too many open catalogs will have the effect of extend- 
ing the users address space or partition size (see also chapter 
9.0 starting on page 225, where VSAM working set and storage 
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Sizes are described). 


° Without Recoverable VSAM catalogs (RCATs), the act of catalog- 
ing an entry in a VSAM catalog was nothing more than making an 
entry into the catalog. The volume containing the data set did 
not even have to be around. With RCAT since the catalog entries 
are duplicated in the CRAs on each owned volume, all of the 
volumes specified must be mounted. Anytime a CRA is accessed 
the volume must be mounted. In MVS these volumes are dynamical- 
ly allocated and mounted. In VS1 we need to specify DD cards so 
the scheduler can mount and access them. 


° Compared to CVOLS, VSAM catalogs suffer from limited access 
problems. 


For update processing, writing into or updating, VSAM catalogs 
allow only single access. This says that while a requester is 
writing, every other requester must wait. For nonupdate type of 
requests, this restriction does not apply, but we still have a 
maximum limitation. The limitation is based on the STRING 
number. Each string specifies a concurrent request.- Tf woz 
string number is 2 we can only have 2 requesters concurrently 
reading. If the string number is 7 the limit is for 7 requés- 
ters and no more. 


B.4.3 CVOL ADVANTAGES (OS/VS) 


Prior to the availability of the Data Management SU (SU 8), CVOL 
support in MVS was minimal. SU 8 has restored CVOL support to the 
level available in SVS, VS1, etc. subject, however, to the single 
catalog structure of MVS (as opposed to dual catalog structure of 
SVS/VS1 where we have an OS/VS System Catalog and a VSAM Master 
Catalog). Some of these differences have been discussed and the 
rest will be pointed out shortly. 


° CVOLS are typically much smaller objects than VSAM catalogs. 
This in turn means that the seek span of the DASD arm when 
accessing acCVOL can be much smaller, which in turn. could 
translate into better performance 


° CVOLS are migratable between not only virtual SCP's but also 
MVT and other non-virtual control programs. 


e There is no limit for concurrent READ access to CVOLS in one 
CPU. This is contrasted to VSAM catalogs that have a maximum 
limit of concurrency of access of 7. 


e CVOLs donot suffer from the so called "space reclamation" 
problem of VSAM catalogs as described earlier (section B.4.2 on 
page 274). They have total space reusage. Although this saves 
DASD space for the user, it can pose other problems that will 
be discussed in section B.4.4 on page 278). 


° CVOL entries are stored with the key field on the DASD device. 
Therefore searches are done on the DASD device by  DASD key. 
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VSAM catalogs have an. index. structure which is read into 
storage and searched via the CPU. CVOL searches mean more DASD 
and channel time, whereaS VSAM searches involve more CPU time. 


CVOLs performance is dependent.on the size of the catalog, the 


number of index levels and the number of names at each level. 


The smaller the size the smaller the .DASD arm seek span. The 
smaller the number of index levels and entries at each level, — 
the lesser the search time and therefore the faster the access. 


It is possible to chain CVOLs such that a data set can be found 
via searching multiple CVOLs chained together. Another way to 
point this out is to indicate that a CVOL can point to CVOL and 
so on. VSAM catalogs can not point to other VSAM catalogs (no 
chaining) with the exception of the Master catalog pointing to 
user catalogs or to a CVOL (MVS only). User catalogs can not 
point to user catalogs. 


4,4 CVOL DISADVANTAGES (COS/VS) 


CVOLS do not Support VSAM data sets. VSAM catalogs support both 
VSAM and nonvVvSAM. 


Although, as pointed out earlier, CVOLsS have total space reuse, 


this can be done at the expense of some performance. It is 
entirely possible that over a period of time with additions 
and/or deletions, CVOLS can become fragmented to the point that 
the DASD arm can "ping-pong" back and forth between cylinders 
far apart. This is a characteristic of large very active oic 
CVOLs. The obvious solution to the problem is eventual reorgan- 
ization, which leads us into the next topic. 


Certainly, compared to VSAM catalogs, CVOLs suffer from the 


lack of comprehensive utility support. The only utility avail- 
able for any CVOL activity in terms of backup, recovery, 
reorganization etc. is IEHMOVE which is not exactly near and 


dear to too many hearts. Most shops have their own user-written 
version of a utility to backup and reorganize CVOLs. 


System access to CVOL entries, in an MVS environment, is 
through qualified data set names. By system access this means 
scheduler allocation activity via JCL. Generally speaking 
access in MVS is always through the MCAT via qualified data set 


names and "SYSCTLG" pointers in the MCAT. 
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The only exception is where a user through IEHPROGM or. some 


user code, writes a CAMLST macro specifying a CVOL parameter. 
Access in this case is directly to the particular CVOL, but 
even in this case the SYSCTLG entry in the MCAT must exist, 
Since the scheduler still accesses the MCAT to find out the 
CVOL devicetype. This essentially indicates that all data set 
names in a CVOL must be qualified and the first level qualifier 
must be an ALIAS name of the CVOL and reflected in the MCAT. 
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APPENDIX C 


The following device 
Access Method Services manual and is valid for all systems: 


C.2 


ACB 
AIX 
AMS 
CA 
CI 
CIDF 
CNV 
CRA 
DASD 
DCB 


DSCB 
ESDS 
HKR 
Tcl 
IS 
KSDS 
LKR 
LR 
MCAT 
RBA 
RCAT 
RDF 
RPL 
RRDS 
39 
UCAT 
VTOC 


lotto ut t @ t W & tft wou t t@ an a ott 


DEVICE TYPE TRANSLATE TABLE 


type translate table has 


LISTCAT Code Device T 
3000 8001 9 TRK TAPE 
3040 200A 3340 (35M/70M) 
3050 2006 2305-1 
3050 2007 2305-2 
3050 2009 3330-1,2 
3050 200B 3350 
3050 200D 3330-11 
3058 2009 3330V 
3080 8001 7 TRK TAPE 
30C0 2008. 2314/2319 


LIST OF ABBREVIATIONS 


Access Method Control Block (VSAM DCB equivalent) 
Alternate Index 

Access Method Services (abbreviation not used any more) 
Control Area | 

Control Interval 

Control Interval Definition Field | 

Control Interval Cused for control interval access) 
Catalog Recovery Area 
Direct Access Storage Device 
Data Control Block (OS/VS 
nonVSAM data set) 

Data Set Control Block (in the vee? 

Entry Sequenced Data Set 

High-kKeyrange 

Improved Control Interval access 

Index Set (part of the index) 

Key Sequenced Data Set 

Low-Keyrange | 

Logical Record 

VSAM Master Catalog 

Relative Byte Address 

VSAM Recoverable Catalog (user or master catalog) 
Record Definition Field 
Request Parameter List (VSAM control block) 
Relative Record Data Set 

Sequence Set (part of the index) 

VSAM User Catalog 

Volume Table Of Contents (disk directory) 


control block to describe 
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BUFND DOS/VS 212 
BUFND OS/VS 215 
BUFNI DOS/VS 212 
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format DOS/VS 212 
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manuals 2 7 
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KSDS direct 24 
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extract from LISTCAT 148 
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description 50 
Sizes 249 
ALTER 
command overview 58 
example 58,121 
free space 121 
password 121 
REMOVEVOLUMES 181 


Alternate Index 
access*® 36 
allocation (LISTCAT) 
data component 150 
index component 149 
cluster 30 
components 30 
deletion Cexample) 173 
description 29 
entry in catalog 51 
export 122 
for ESDS 
definition 129,134 
description 31,34 
for KSDS 
definition 111,116 
description 31,33 
import 124 
loading 113 
parameters 
KEYS 110 
NONUNIQUEKEY 110 
NOUPDATE 110 
 NOUPGRADE 110 
RELATE 110 
UNIQUEKEY 110 
UPDATE 1190 
UPGRADE 110 
update examples 37 
upgrade set 31 
structure 32 
With Path 29,35 
working set 
DOS/VS 229 
MVS 231 
SVS 233 
VS1 235 
Alternate Key 12,30 
AMASPZAP service aid (OS/VS) 
alter ds security bit 269 
alter ownership bit 269 
print the catalog 268 
Assembler Macros 
‘Compatibility 5 
description 217 
ACB 217 
BLDVRP (OS/VS) 222 
CHECK 221 
CLOSE 222 
DLVRP (COS/VS) 222 
ENDREQ 221 
ERASE 221 
EXLST 218 
GENCB 219 
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Assembler Macros (cont. ) 
GET 220 
GETIX 222 
MODCB 219 
MRKBFR (OS/VS) aes: 
OPEN 220 
POINT macro 221 
PUT 221 
PUTIX 222 
RPL 218 : 
SCHBFR (OS/VS) 223 
SHOWCAT 220 
SHOWCB 219 
TESTCB 219 
WRIBFR COS/VS) 222 
ATTEMPTS parameter 55 
Backing up 


catalog (see Catalog) 171,172 
data set (see Data set) 66,122 


BACKUP/RESTORE (DOS/VS) 253 
Backward processing 22 
Base 
cluster 
access 36 
description 29 
key 12 
Basic description of VSAM 5 
BDAM 
description 71 
versus VSAM 74 
BISAM description 71 
BLDINDEX 
command overview 59 
description 30 ae 
example CESDS) 130,135 
example (KSDS) 113 
BLDVRP macro (OS/VS) 222. 
BPAM description 71 
BSAM description 72 
Butfers 
description 10,190 
for direct access 192 
for multiple strings 194. 
for sequential access 193 
for skip seq. access 192 
non-~shared resources 190 
BUFND parameter 
default 190 
DOS/VS ACB 212 
OS/VS ACB 215 
OS/VS JCL 213 
suggested value for. 
direct access 192 
sequential access 193 
skip-sequential access 192 
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BUFNI parameter 
default 190. 
DOS/VS ACB 212 
OS/VS ACB 215 _ 
OS/VS JCL 213 > 7 
suggested value for 
direct access 192 
sequential access 193 
skip- sequential access 192 
BUFSP parameter 
default 190 
DOS/VS ACB 212 
DOS/VS JCL 211 
for OS/VS catalog 271 
in DEFINE command 190 
OS/VS ACB 215 
OS/VS JCL 213 
suggested value for 
direct access 192 
sequential access 193 
skip-sequential access 192 
CA see Control Area 
Calculate 
KSDS size 197 
used catalog space 247 
Catalog > 
allocation erende 263 
backup 
BACKUP/RESTORE (DOS) 253 
ITEHDASDR descr. (0S) 255 
IEHDASDR examples (0S) 256 
REPRO description 254 
REPRO examples 171,172 
BUFSP parameter (OS/VS) 271 
calculate used space 247 
CCR catalog control record | 
format 247 | 
printout 248 
change allocation 263 
change catalog name 265 
change master catalog 
DOS/VS. 79 
MVS 81 
SVS 83. 
VS1 83 
cleanup 181 
components 49 
considerations 47 
content 50 
description 50 
device conv. nonrec. cat. 
MVS 257 Sea 
DOS/VS,SVS,VS1 258 
device conv. rec. cat. 259 
dynamic allocation MVS 43 


Catalog (cont. ) 
entries 51 
High-/Low-Keyrange logic 242 
High-Keyrange 241 
layout 49 
Low-Keyrange 241 
multiple strings (OS/VS) 271 
name change 265 
ownership of volumes 47 
performance (OS/VSO 271 
philosophy 47 
print the catalog 
With A/HMASPZAP 268 
with IEHDASDR 267 
with LISTCAT 142 
recoverable catalog 
description 250 
versus nonrecoverable 252 
recovery area : 
description 250 
Open and Close 251 
pointer in VTOC 49 
Size 195 
space allocation 250 
recovery | 
introduction 250 
versus nonrecovery 252 
reorganization 
introduction 261 
nonrecoverable catalog 262 
recoverable catalog 263 
self describing records 242 
shared UCB (OS/VS) 271 
sharing 51 
size 195 
Space allocation 
DOS/VS 45 
OS/VS 45 
structure 243 
used space calculation 247 
CCR catalog control record 
format 247 
printout 248 | 
Change data set attributes 
see ALTER : 
Change (with ALTER) 
FREESPACE 121 
PASSWORD 121 
CHECK macro 221 
CHKLIST | 
command overview 59 
CHKPT macro 59 
Choosing 
the data CI-size 185 
the index CI size 186 


CI see Control Interval 
CIDF description 7 
Cleanup volumes 181 
CLOSE macro 222 
Cluster , 
alternate index cluster 30 
base cluster 29 
description 16 
entry in catalog 51 
entry displayed 
with LISTCAT 152 
names 43 
Commands 
overview 57 
ALTER 58,121 
BLDINDEX see BLDINDEX 
CHKLIST 59 
CNVTCAT 57 
DEFINE see DEFINE 
DELETE see DELETE 
EXPORT 122 
EXPORTRA 167 
IMPORT 124,166 
IMPORTRA 169 
LISTCAT 140,142 
LISTCRA 160,163 
PRINT see PRINT 
REPRO see REPRO 
RESETCAT 164 
VERIFY 126 
Compression 
see Key compression 203 
Connecting a user catalog 
with the master catalog 166 
Control Area (CA) 
description 10 
Size 10,195 
size calc. by VSAM 187 
split | 
direct insert 202 
mass insert 209 
restriction 96 
structure 10. 
Control (information) field 
CIDF 7 
RDF 7 
Control Interval (CI) 
calc. formula (index) 206 | 
capacity (index entries) 195 
choosing data CI-size 185 
choosing index CI-sizge 186 
description 6 
processing 
description 74 
ESDS 27 
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Control Interval proc. (cont. ) 


KSDS 24 
RRDS 29 
size Ds | 
calc. formula (index) 206 
recommendations 186 
split 201 
structure 7 
with fixed records 8 
With var-length records 8 
Control block macros 217 
Convert ISAM to VSAM 
description 76 
overview 67 
Copy functions see REPRO 
CRA see 
Catalog recovery area 
Cross-~partit. sharing 95 
Cross-system sharing 936 
Create VSAM ObJeCrs 6 
CVOL | 
advantages 277 
cataloged in VSAM 43. 
disadvantages 278 
versus VSAM catalog 272 
DAM see BDAM 
Data 
butfers 190 
CI-size recommendations 185 
component 
calculation (KSDS) 197 
description 16 
entry in catalog 51 
names 43 
set 3 
backup with IEHDASDR 255 
backup with REPRO 66,122 
buffer EXCPs 193 
comparison 39 
conversion 76 
cross-partit. sharing 95 
cross-system sharing 96 
multi-cylinder ds 187 
multi-volume ds 188 
names 43 | 
Sharing see SHAREOPTIONS 
Size 195 
space allocation 187 
space calculation 197 
small data sets 187 
suballocated 40 _ 
unique 40 
set security bit 
alter with A/HMASPZAP 269 
description 45 
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Data set security bit (cont.) 


display 246. 
space 
allocation 45,189. 
description 40 
example 105 
extension 189 
names 43 
primary allocation 189 
secondary allocation 189 
size 195 
suballocatable 40 
unique 40 
structure 
control area 10 
control interval 6 
DATASET macro (MVS) 80 
DDNAME sharing (OS/VS) 214 
DEFINE | 
BUFSP parameter 190 
command overview 60 
DEFINE ALIAS 
example 183 
DEFINE ALTERNATEINDEX 
ESDS example 129,134 
KSDS example 111,116 
DEFINE CLUSTER 
command overview 60 
ESDS example 127 
KSDS example 106 
KSDS parameter 87 
RRDS example 138 
DEFINE MASTERCATALOG 
example 100 
DEFINE NONVSAM 
example 183 
DEFINE PATH for 
ESDS (Cexample) 129,134 
KSDS Cexample) 111,116 
DEFINE SPACE 
example 105 
DEFINE USERCATALOG 
command overview 60 
example 102 . 
Parameter description 
FILE 88 
FREESPACE 88 
IMBED/REPLICATE 89,190 
KEYRANGES 91 
NAME 93 
RECORDSIZE 94 
SHAREOPTIONS 95 
SPEED/RECOVERY 97 — 
SUBALLOCATION/UNIQUE 98 


Poe 


Delete a record 
in KSDS and RRDS 39 
in KSDS description 21 
DELETE 
AIX (Cexample) 173 
all VSAM objects 
DOS/VS 179 
OS/VS 181 
command overview 61 
ESDS Cexample) 175 
KSDS (Cexample) 174 
NOSCRATCH (MVS) 252 
RRDS (Cexample) 176 
SPACE Cexample) 177 
suballocatable space 177 
USER CATALOG (ex.) 178 
Device 
characteristics table 196 
type translate table 279 
Direct access 
buitfer 192 
ESDS 27 
KSDS 
addressed 24 
keyed 23 
processing 23,27,29 
Disconnecting a user catalog 
from the master cat. 165,182 
Distributed free space 
| see Free space 
DLBL statement (DOS/VS) 211 
DLVRP macro (OS/VS) 222 
DOS/VS 
catalog sharing 51 
change the master cat. 79. 
compatibility 5 
JCL parameter 211 
Load a new SDL/SVA 79 
manuals 2 
space allocation 45 
Supervisor parameters 79 
SY¥Snnn CAcec.Meth.Serv.) 86 
user information 2 | 
DRWDASDR (COS/VS) see IEHDASDR 
DSNAME sharing (COS/VS) 214 
Dump/Restore VSAM vol. 255,256 
EODAD exit 218 
ENDRE@ macro 221 
Entries in catalog 51 
Entry-sequenced data set 
see ESDS | 
ERASE macro 221 
ESDS (Entry-Seq. Data Set) 
base cluster 16 
cluster 16 


ESDS (Entry-Seq. Data Set) Ccont.) 


components 16 
definition Cexample) 127 
deletion (example) 175 
description 14 
loading 
description 67 
example 128 
logical red processing 73 
positioning 27 | 
printing (example) 131 
processing 26 
requests 26 
structure 14 
Exclusive control 96 
EXCPs reading data buffer 193 
EXLST macro | | 
description 218 
format DOS/VS 212 
format OS/VS 215 
EXPORT 
command overview 61 
DISCONNECT 165,182. 
example 122 Os 
EXPORTRA : 
command overview 63 
description 259. 
example 167 


Extending 


a data set 189 
records 20 
EXTENT statement (DOS/VS) 211 
FILE parameter 88. | 
Fixed-length records 
detinition 94 
description 8 
Forward processing 22 
Free space 
calculation by VSAM 88 
changing with ALTER 121 
description 88 
loading with different 
values 199 
logical examples 19,21 
FREESPACE parameter descr. 88 
Fi timestamp 245 
FU timestamp 245 
GENCB macro 219 
Generation data groups 
entry in catalog 51 
in catalog 275 
Generic Key 23 
GET 
examples 36 
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GET (cont. ) 
macro | | 
description 220 
format DOS/VS 212 
format OS/VS 215 
GETIX macro 222 
Guidelines to this manual 1 
High level languages 78 
High-Keyrange of catalog 
description 241. 
overview 50 
High- used RBA 
description 16 
display with LISTCAT 156 
HMASPZAP service aid (OS/VS) 
see AMASPZAP 
ICI option in ACB 74 
IEHDASDR utility (OS/VS) 
backing up examples 256. 


backing up the catalog 255 


print the catalog 267 
IKQVDU-Utility (DOS/VS) 179 
IMBED parameter 

combinations 90 

description 89,190 
IMPORT 

command overview 61 

CONNECT a user catalog 166 

KSDS and its AIXs 124 
IMPORTRA 

command overview 63 

description 259 

example 169 
Index 

alternate index see 

Alternate index 

buffers 190 

component 

calculation (KSDS) 198 

description 18 

entry in catalog 51 
Control Interval (CI) ~ 

capacity Centries) 195 

formula 206 | 

recommendations 186 

index set 18 

level 18 

names 43 

parameter combinations 90 

performance 190 

primary index 13,18 

record 18 

replicate 89 

sequence set 18 

structure 18 
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Inserting | 
Single records 20 


Single/Mass-insertion 23,207 


Installation of VSAM 
in DOS/VS 79 
in SVS 83 
in VS1 83 
in MVS 80 
ISAM | 
backup/unload 66 
converting to VSAM 67 
description 72 
Interface Program 
description 76 
example 76 
versus VSAM 75 
JCL 
parameter 
DOS/VS 211 
OS/VS 213 
to macro relationship 
DOS/VS 212 
OS/VS 215 
JOBCAT (COS/VS) 213 
JRNAD exit 218 
Key 
alternate Key 12,30 
base Key 12 
compression 203 
generic Key 23 
length (size) 196 
primary Key 12 
Keyed processing 
direct 23 
overview 24 
sequential 22 
skip-sequential 23 
KEYRANGES 
catalog Keyranges 50 
description 91 
examples 91 | 
With diff. free space 199 
KEYS parameter 110 
Key-sequenced data set 
gee KSDS 
KSDS (Key-Seq. Data Set) 
allocation (LISTCAT) 
data component 149 
index component 149 
base cluster 16 
CA structure 11 
calculate size 197 
cluster 16 
components 16 
COpPpy data to SAM file 120 
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KSDS (Key-Seq. Data Set) (Ccont. ) 


data component 16 

definition (example) 106 

deletion (example) 174 

description 12 

export 122 

import 124 

index 18 

index component 16 

loading the data set 
description 67 


normal loading (ex.) 108 


With diffi. free space 199 


positioning 25 
printing 109 
processing 22 
requests 22 
structure 13,19 
verify 126 
working set 

DOS/VS 229 

MVS 231 

SVS 233 

VS1 235 

LERAD exit 218 


LISTCAT 


ALL Cexample) 142 

command overview 65 

explanation of fields 
cluster entry 152 


cl 
el 
ro D 
ei 
cl 


data component entry 
data cmp. statistics 
data cmp. allocation 
data cmp. vol. info. 
index component 158 


153 
155 
156 
157 


catalog volume record 159 
extract allocations 148 


NAME 


LISTCRA 


Cexample) 140 


command overview 65 
COMPARE (Cexample) 163 
NOCOMPARE (Cexample) 160 


Load new SDL/SVA (DOS/VS) 79 


Loading 
a data set (descr.) 67 


ds with diff. 


ESDS 
KSDS 


128 
108 


options 937 


RRDS 


139 


Logical record 
length (size) 196 
processing 73 


relation to physical red 9 


free space 199 


Low-~Keyrange of catalog 
description 241 
overview 50 
Macros description 217 
Manuals 2 
Mark delete ESDS record 26 


Mass-sequential insertion 23,207 


Master catalog 
definition 100 
master password 54 
recoverable/ynonrec. 252 
using a user catalog as 
master catalog 79,81 
Merging records 66 
MODCB macro 219 — 
MRKBFR macro (COS/VS) 223 
MSS (3850) default parameter 
in LISTCAT listing 153 
Multiple cylinder data sets 
(not multivolume) 187 
Multiple strings 191,194 
Multivolume data sets 188 
MVS 
catalog sharing 51 
change the master cat. 81 
create a master catalog 80 


CVOL versus VSAM catalog 272 


DATASET macro 80 
install VSAM 80 
manuals 2 
naming restrictions 94 
storage requirements 237 
use a user catalog as 
master catalog 81 
user information 2 
NAME | 
parameter description 93 
qualified 94 
NOIMBED parameter 90 
Nonrecoverable catalog 
see Catalog 
Nonsuballocatable see Unique 
NONUNIQUEKEY parameter 110 
Non-VSAM data set | 
definition 183 
entry in catalog 51 
NOREPLICATE parameter 90 
NOUPDATE parameter 110 
NOUPGRADE parameter 110 
OPEN 
examples 36 
macro 
description 220 
format DOS/VS 212 
format OS/VS 215 
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os/vs 


cat. pointer to VSAM MCAT 83 


compatibility 5 
JCL parameter 213 
Password bit 


see Data set security bit 


Service Aids 268 
space ‘allocation 45 
Utilities 255,267 © 
Out-of-synch condition 250 
Ownership 
bit 
description 44 
display 246 
concept. 4u3 
reset ownership 
DOS/VS with IK@VDU 179 


OS ALTER REMOVEVOLUME 181 


OS with A/HMASPZAP 269 


test for space alloc. 45,189 


Path 
access 36 
description 35 
entry in catalog 51 
to ESDS (example) 129,134 
to KSDS (example) 111,116 
Passwords 


changing with ALTER ex. 121 


for the master catalog 54 
definition in DEFINE 103 
definition with ALTER ex. 
description 52 
retry 55 
specified in user pgm. 55 
usage on diff. levels 54 
Performance 
buffer 190 
catalog (OS/VS) 271 
choose data CI size 185 
choose index CI size 186 
data set space 187 
index 190 
Physical record 
description 9 
size 196 
POINT macro 221 
Positioning for 
key sequential access 25 
skip seq. access 25 
Primary : 
index 
space allocation 187, ree 
structure 13,18 
key 12,390 
Space allocation 189 
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PRINT 


AIX Cexample) 114,132. 
catalog | 
with H/AMASPZAP 268. 
With IEHDASDR 267 
with LISTCAT 142 
command overview 65 
ESDS 131 : 
KSDS 109 
parts of a base cluster 
via a path (ex.) 115,119 
parts of an AIX 114,118 
Processing of data sets 22 
PUT 
examples 36 
macro 221 
description 221 
format DOS/VS 212 
format OS/VS 215 
PUTIX macro 222 
QISAM description 72 
QSAM description 72 
Qualified names 94 
RBA (Relative Byte Address) 
description 10 
high-used RBA 
description 16 
display with LISTCAT 156 
used in an ESDS 34 
RDF description 7 
Record 
data structure 7 
description — 
fixed-length 8 
logical 9 
physical 39 
spanned 11 
variable length 8 
length 
restrictions 94 
Size 196 
RECORDSIZE parameter descr. 


Recoverable cat.(see Catalog) 


description 250 | 
versus nonrec. catalog 252 
RECOVERY parameter descr. 97 
RELATE parameter 110 
Relationship of data access 

to data organization 71 
Relative 

byte address see RBA 

record data set see RRDS 

record number 15 
Release (VSAM release) 152 
Relinquish ownership 43 


Reload a user catalog 172 
Reorganize a 
catalog 261 
data set 66 
REPLICATE parameter 
combinations 90 
description 89 
REPRO 
catalog backup 
description 254 
examples 171,172 
command overview 66 
copy catalog - catalog 
(MVS only) 272 
copy data of a KSDS to a 
SAM-£file on disk (ex.) 120 
load ESDS Cexample) 128 
load KSDS (Cexample) 108 
load RRDS (Cexample) 139 
reload user catalog from 
backup tape (example) 172 
reorganize data set 66 
unload - backup : 
catalog (example) 171 
recoverable catalog 252 
Request | 
macros 220 
types 
ESDS 26 
KSDS 22 
RRDS 28 
RESETCAT 
command overview 69 
example 164 
usage for 
device conversion 253 
unload/reload 254 
Resetting a reusable ds 17 
Restore a damaged 
data set 66,122 
Reusable data set 
description 16 
resetting 17 
RPL macro 
description 218 
format DOS/VS 212 
format OS/VS 215 
RRDS (Relative Record Data Set) 
base cluster 16 : 
clustexr 16 
components 16 | 
definition (example) 138 
deletion (example) 176 
description 15 


RRDS (Relative Record Data Set) 
loading 
description 67 
example 139 
logical red processing 73 
positioning 29 
processing 28 
requests 28 
slot description 15 
structure 15 
SAM 
description 73 
versus Sequential VSAM 73 
SCHBFR macro (OS/VS) 223 
Secondary space alloc. 189 
Security author. routine 53 
Sequence set 
see Index sequence set 
Sequential 
access 
buffer 193 
description 22,26,28 
insertion 23,207 
processing | 
ESDS 26 
KSDS 22 
RRDS 28 
Service Aids (DOS/VS) 179 
Shared 
resources macros 222 
UCBs (COS/VS) 271 
SHAREOPTIONS 
cross-~partition/region 95 
cross-system 96 
description 95 
Sharing 
catalogs 51 
data sets 95 
DDNAME/DSNAME COS/VS) 214 
SHOWCAT macro 220 
SHOWCB macro 219 
Single/Mass-insertion 23,207 
Sizes 
allocation unit 249 
catalog 195 
control area 10,195 
control interval 195 
CRA 195 7 | 
data set 195 
data space 195 
device characteristics 196 
key length 196 
logical record length 196 
physical record size 196 
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Ccont. 


) 


Skip- sequential processsng 
buffer 192 
KSDS 23 
RRDS 28 
Slot description 15 
Small data sets 187 
space 
allocation 
description 45,189 
extension 189 | 
for a data set 187 
primary 189 
secondary 189 
calculation 
for a catalog 247 
for a KSDS 197 | 
definition (example) 105 
deletion 
suballocated space ex. 177 
unique space 40 
Spanned records 
description 11 
length 196 
structure 12 
SPEED parameter descr. 97 
Splits 
CA split 202 
CI split 201 
STEPCAT COS/7VS) 213 
Storage 
location o£ routines 
DOS/VS 225 
MVS 227 
SVS 226 
VS1 226 
requirements 
DOS/VS 236 
MVS 237 
“SVS 238 
VS1 239 
Strings 
concurrent processing 223 
description 191 
multiple strings buffer 194 
STRNO parameter 
see Strings 
Structure of 
catalog 243 
control area 10 
control interval 6 
ESDS 14 
 RKSDS 13,19 
RRDS 15 
Suballocated 
cluster 40 
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Suballocated (cont. ) 
data set 40 
Suballocatable 
data space 40 
SUBALLOCATION parameter 98 
Subset mount 216 
SUPERZAP (COS/VS) see AMASPZAP 
SVS 
catalog sharing 51 
change the master catalog 83 
install VSAM 83 
Manuals 2 
storage requirements 238 
use a user catalog 
as master catalog 83 
user information 2 
SYNAD exit 218 
SYySnnn (DOS/VS) 86 
System Generation fox VSAM 
DOS/VS 79 
MVS 890 
SVS - VS1 83 
SYS1.NUCLEUS member (MVS) 81 
TESTCB macro 219 
Timestamps 
change with 
IKQ@VDU CDOS/VS) 179 
H/AMASPZAP (OS/VS) 270 
description 244 
mismatch 254 
Trackhold facility (DOS/VS) 96. 
Translate table 279 | 
Types of data sets 12 
Unique , 
cluster 40 
data set 40 
data space 40 
UNIQUE parameter 98 
UNIQUEKEY parameter 110 
Unload - backup 
catalog (example) 171 
recoverable catalog 252 
UPDATE | 
parameter 110 
restrictions 38 
Updating 
alternate index 37 
records 20 
UPGRADE 
examples 37 
parameter 110 
Upgrade set 
description 31 
entry in catalog 51 


User catalog 
advantages (OS/VS) 273 
allocation (LISTCAT) 
data component 148 
index component 148 
connecting to mast. cat 166 
definition 102 
deletion (example) 178 
disadvantage (OS/VS) 274 
disconnecting (ex.) 165,182 
entry in master catalog 51 
philosophy 47 
recoverable/nonrec. 252 
reload catalog from 
backup tape 172 
unload/backup catalog 171 
usage 47 
using as a master catalog 
DOS/VS 79 
MVS 81 
SVS 83 
VS1 83 
versus CVOL (MVS) 273 
Variable-length records 
definition 94 
description 8 
VERIFY 
command overview 68 
example 126 
macro 68 
Virtual storage requirements 
see Storage requirements 
Volume 


cleanup 
DOS/VS 179 
OS/VS 181 


dump/restore 255,256 

entry in catalog 
description 51 
display with LISTCAT 159 

ownership 47 

ownership bit reset with 
DOS/VS IK@VDU 179 


OS/VS ALTER REMOVEVOL. 181 


OS/VS A/HMASPZAP 269 
timestamp 
change (DOS/VS) 179 
change (OS/VS) 270 
description 244 
display with LISTCAT 159 
mismatch 254 
VSAM release 152 
vSs1 
catalog sharing 51 


change the master catalog 83 


VS1 Ccont.) 
install VSAM 83 
storage requirements 239 
use a user catalog 
as master catalog 83 
user information 2 
VTOC 
F1 and F4Y DSCB (Labels) 245 
Where is VSAM in storage 
DOS/VS 225 
MVS 227 
SVS 226 
VS1 226 
Working Set 
DOS/VS 
for AIX processing 229 
for a KSDS data set 228 
MVS/VS 
for AIX processing 231 
for a KSDS data set 230 
SVS/VS 
for AIX processing 233 
for a KSDS data set 232 
VS1/VS 
for AIX processing 235 
for a KSDS data set 234 
WRIBFR macro (OS/VS) 222 
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